awesome-ai-prompts

Fix the bug in issue `#N` in this `awesome-ai-prompts` repository. Do not
start coding until the bug is reproduced and the root cause is proven. A fix
without a reproduced failure is not a fix - it is a guess.

## Steps

1. **Reproduce** - Read the issue, then read the files it implicates. Run the
   failing command or state exactly how the behavior is wrong, and capture the
   actual output versus the expected output.
2. **Root-cause** - Explain the mechanism precisely: which file and line,
   which check or script, which README entry. Use `git log` and `git blame` on
   the relevant file to see when the behavior appeared. Prove the cause before
   touching anything.
3. **Minimal fix** - Make the smallest change that removes the failure. Do not
   refactor, reword, or reformat unrelated content in the same edit.
4. **Prove it** - Re-run the original failing reproduction and show before and
   after. Run the repo gates: `bash scripts/check-links.sh` and
   `bash scripts/check-consistency.sh`, markdownlint on the changed files, and
   `bash -n` on any changed shell script.
5. **Guard against regression** - Where the repo allows it, add the check that
   would have caught this bug (for example a script assertion or a stricter
   README convention). If nothing reasonable can be added, say why.
6. **Commit and PR** - One conventional `fix:` commit referencing the issue,
   and a PR description showing the reproduced failure, the root cause, and the
   verification output.

## Rules

- No claim of a fix without the reproduced failure and the passed checks shown.
- No unrelated edits and no silent convention changes.
- If the reported bug cannot be reproduced, say so and ask instead of
  inventing a fix.

## Verification

The after-state of the reproduction no longer fails, and every gate named in
step 4 passed with its output shown.

Help me add a new prompt to this `awesome-ai-prompts` repository. Every prompt
here follows strict conventions and CI enforces them, so read the rules before
writing anything. Do not write the file until we have agreed on the idea.

## Steps

1. **Read the conventions first** - Read `CONTRIBUTING.md`,
   `.github/PROMPT_TEMPLATE.md`, and two or three existing prompts in the
   category you intend to use. Note the exact structure: an H1 title, a short
   copy-paste usage note, a `---` divider, then the prompt body.
2. **Confirm the idea is new** - List the closest existing prompts and say how
   this one is different. If it duplicates an existing prompt, stop and propose
   a distinct idea instead. Never add a near-copy.
3. **Draft after the divider** - Write the body below the `---` divider. Keep
   it direct and prescriptive: numbered `## Steps` with bold lead-ins, a
   `## Rules` list, and a `## Verification` section that names actual commands.
   Ground it in "verify, don't guess": no claim without a way to check it.
4. **Follow the repo's rules** - Tool-agnostic (works with Claude, ChatGPT,
   Copilot, Cursor, opencode, and others). Self-contained: everything the user
   pastes lives inside the block. No em dashes anywhere, use an ASCII hyphen.
   Flag the file with `[spec]` in README and CHANGELOG only for multi-section
   prompts for big, risky work.
5. **Name and place it** - `kebab-case-action-prompt.md` in the matching
   category folder. Never put prompt files at the repo root.
6. **Update the index** - Add a one-line entry in the matching README section
   followed by a short description ending in a period, and bump that category's
   count in the Contents list.
7. **Add a changelog entry** - Under `## [Unreleased]` in `CHANGELOG.md`, add a
   line that names the file in backticks, then a hyphen, then a short
   description.
8. **Verify before claiming done** - Run `bash scripts/check-links.sh` and
   `bash scripts/check-consistency.sh`, and run markdownlint on the changed
   files with `npx --yes markdownlint-cli2@0.17.2 <file>`. All must pass. Show
   me the script output; never just your word that they passed.
9. **Commit and PR** - One conventional commit (`docs: add <name> prompt`),
   reference any related issue, and write a PR description that explains why
   this prompt belongs here.

## Rules

- Never write a prompt that demands verification without naming the actual
  command or check that runs it.
- Never say a check passed unless you ran it and saw the output.
- Keep the change tight: one prompt per PR, no unrelated wording or format
  edits to existing prompts.
- If a rule is ambiguous, ask before writing.

## Verification

Run every command in step 8 and paste the outputs. Confirm the README section
lists exactly one new entry, the Contents count matches the folder, and the
CHANGELOG entry names the new file.

Write `[the new prompt]` as a one-pager in this repository - a
self-contained prompt for one quick task that fits on a single printed page.
Match the field contract below, then verify the result against the same
checks this file satisfies.

## Field contract

| Field        | Rule                                                             |
| ------------ | ---------------------------------------------------------------- |
| H1 title     | `# Reusable prompt: <kebab-case name>`, no `[spec]` suffix       |
| Usage note   | 1-2 lines explaining when to paste the block                     |
| Divider      | A lone `---` between the note and the prompt block               |
| Opening      | One imperative sentence with `[placeholders]` naming the task    |
| Steps        | `## Steps` - numbered, each step names the action and its output |
| Verification | `## Verification` - checkbox list the agent must satisfy         |
| Rules        | `## Rules` - 3-5 "Never/No/If" lines that price mistakes         |
| Size         | Prompt block ~45 lines / ~550 words max; whole file one page     |
| Extras       | No extra sections, no sub-tasks, no references to other prompts  |

## Method

1. Name the single task the prompt completes, in placeholders.
2. Keep one success path; do not branch on scenarios.
3. Build Steps, then derive Verification and Rules from what could go wrong.
4. Cut until the block fits the page - cut steps, never verification.

## Verification

- [ ] The whole file fits on one printed page (block `<=` 45 lines or ~550
      words).
- [ ] Every field in the contract above is present, and nothing beyond it.
- [ ] Naming follows `kebab-case-prompt.md` in the matching category folder.
- [ ] Indexed in the README, and `bash scripts/check-links.sh` passes clean.

## Rules

- Never write a one-pager for a task that needs scope negotiation or a
  verification matrix - that is a spec prompt.
- Never exceed the budget by dropping verification; drop optional steps.
- Never reference other prompts or assume context a stranger lacks.

Review pull request `#N`, which changes prompts in this `awesome-ai-prompts`
repository. Return an explicit verdict: APPROVE, READY AFTER FIXES, or REQUEST
CHANGES, with every finding tied to a file and line. Do not skim - read the
whole diff and the full text of every changed prompt.

## Steps

1. **Read the PR in full** - Read the description and every changed file,
   especially the complete body of each new or edited `*-prompt.md`, above and
   below the `---` divider.
2. **Run the repo's own gates** - Run `bash scripts/check-links.sh` and
   `bash scripts/check-consistency.sh`. They must pass clean; if they fail,
   name each failing check with its output.
3. **Check structure** - Every prompt starts with an H1 title (`# Reusable
prompt: ...`), has a short usage note, a `---` divider, then the body. Files
   sit in a category folder, are kebab-case, and end in `-prompt.md`. No em
   dashes anywhere; use an ASCII hyphen.
4. **Check the index is in sync** - The README section links the file, the
   one-line description is accurate, the Contents count for that category
   matches the folder, and a `## [Unreleased]` CHANGELOG entry names the file.
5. **Review quality, not just format** - The prompt must be tool-agnostic,
   self-contained (everything to paste sits after the `---`), and
   verification-first: every command or check it names must be real and
   runnable in this repo. Flag any step that asks an agent to "verify" without
   naming how.
6. **Verify claims about the repo** - If the prompt references scripts,
   workflows, or conventions, confirm they exist and behave as described by
   reading `scripts/`, `.github/workflows/`, and `CONTRIBUTING.md`.
7. **Give a verdict** - Summarize what is right, list each fix with the exact
   file, and approve only when the gates pass, the index is in sync, and the
   prompt would actually keep an agent honest.

## Rules

- Never approve on the author's description alone; the checks must run.
- Separate taste from mistakes: note a style preference separately from a rule
  violation.
- Keep the review in the repo's terms: mergeable first time, verified, tight
  scope.

## Verification

Show the outputs of the two scripts and the markdownlint run, and state that
the em-dash scan was clean, with the commands you used.

Help me complete the issue I point you at in this `awesome-ai-prompts`
repository and land it as a pull request a maintainer will merge. This is a
catalog of copy-paste prompts, so most issues are about wiring, wording, or new
prompts - read the conventions before changing anything.

## Steps

1. **Understand the ticket** - Read the issue and the files it touches.
   Restate the ask in one sentence and list the files you expect to change.
   Ask me before proceeding if anything is ambiguous.
2. **Reproduce or show the before-state** - For a bug, broken link, or failing
   check, reproduce the failure first and show me the actual output. For a
   feature or new prompt, show me the current state before proposing a change.
3. **Read the conventions** - `CONTRIBUTING.md`, `.github/PROMPT_TEMPLATE.md`,
   and a neighboring prompt when the issue is about prompts.
4. **Scope the change** - State precisely what will change: for prompt work,
   one new file in a category folder, one README entry plus a Contents count
   bump, and one `## [Unreleased]` CHANGELOG entry. Keep it minimal.
5. **Implement** - Make the smallest change that resolves the issue. Follow the
   repo's rules: tool-agnostic, verification-first, no em dashes, one PR per
   logical change.
6. **Update the derived artifacts** - README entry and Contents count, plus a
   CHANGELOG entry under `[Unreleased]`, exactly when prompts are added,
   renamed, or moved.
7. **Verify** - Run `bash scripts/check-links.sh` and
   `bash scripts/check-consistency.sh`, and `npx --yes markdownlint-cli2@0.17.2`
   on the changed files. Paste the outputs.
8. **Commit and PR** - One conventional commit, reference the issue (for
   example `Closes #N` when it truly resolves it), and open the PR with the
   verification output in the description.

## Rules

- Never change a prompt's substance to satisfy a check; if a check conflicts,
  stop and ask.
- Never claim the issue is resolved unless the failing behavior is gone or the
  missing feature demonstrably exists.
- Keep unrelated files untouched.

## Verification

Confirm the reproduction or before-state from step 2, then the check outputs
from step 7. For a broken link or script, show that the fix catches the old
failure.

Write `[the new prompt]` as a spec prompt in this repository - the format for
tasks where failure is expensive and agent claims need proof. Match the field
contract below exactly, and register the result in the index with the spec
badge.

## Earning the badge

A prompt qualifies as a spec when it must prevent expensive failure: audits,
migrations, platform verification, security work, anything whose wrong answer
ships a regression. Quick single-answer tasks do not qualify - trim those to a
one-pager. Approved spec prompts carry the light-blue `[spec]` badge in the
README and are registered in `SPEC_PROMPTS` in
`scripts/check-consistency.sh`.

## Field contract

| Field        | Rule                                                                                                 |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| H1 title     | `# Reusable prompt: <name> [spec]` - the suffix is mandatory                                         |
| Usage note   | 1-2 lines naming when the heavy format applies                                                       |
| Divider      | A lone `---` between the note and the prompt block                                                   |
| Scope        | `## Define the scope first` - forces platforms, inputs, outputs, and out-of-scope before work starts |
| Deliverables | `## What to produce` - numbered artifacts, each with its evidence shape                              |
| Method       | `## Method` - numbered commands; baseline and measure first where measurable                         |
| Verification | `## Verification` - checkbox gate, exhaustive and every item checkable                               |
| Rules        | `## Rules` - hard "Never" lines naming the risks the gate protects                                   |
| Evidence     | No bare claims; every assertion bound to a run log, matrix, or file:line                             |
| Index        | README entry with badge, `SPEC_PROMPTS` registration, changelog entry                                |

## Method

1. Decide the badge with the qualifying rule above, before writing anything.
2. Force the scope: name platforms, inputs, outputs, and what is out of
   scope. Work cannot start until scope is stated.
3. Define the deliverables and the evidence shape each one produces.
4. Write the Verification gate, then the Rules that protect it.

## Verification

- [ ] `[spec]` suffix, README badge, `SPEC_PROMPTS`, and changelog entry are
      all in sync.
- [ ] Scope-first is enforced - no work before scope is stated.
- [ ] Every Verification item is checkable by someone new to the task.
- [ ] Out-of-scope is stated, so no unverifiable "done" is possible.
- [ ] `bash scripts/check-links.sh` and `bash scripts/check-consistency.sh`
      pass clean.

## Rules

- Never badge a task a one-pager covers; cheap work gets the cheap format.
- Never end a spec prompt without an explicit acceptance gate.
- Never accept "done" without the evidence the gate names.
- Never register a spec prompt without its badge, index entry, and checks.

Act as my interview coach for coding problems. I'll give you a problem or ask
you to pick one. Run the session like a real technical interview, but with the
coaching controls below.

## How a session runs

1. **Setup** - Either use the problem I give you or pick one at the difficulty
   I ask for, and state it with example inputs/outputs. Ask me about my target
   language and constraints if it matters.
2. **The interview** - Let me attempt the problem. Don't solve it for me. Use
   this scaffold: I say "give me a hint" when I'm stuck, "too much" when you
   over-explain, "verify" to check my approach without giving it away, and
   "solve" when I give up.
3. **Hints, in order** - Start with the smallest useful nudge (e.g. "think
   about what changes the answer - what's the brute force?") before anything
   closer to the answer. Never reveal the optimal solution before I've
   wrestled with the problem unless I ask you to.
4. **Code review** - When I have a solution, review it as an interviewer
   would: correctness, edge cases (empty input, duplicates, large values,
   off-by-one), time and space complexity, and code quality. Be specific and
   concrete.
5. **Debrief** - After the session (or when I say "debrief"), give honest
   feedback: what went well, where I wasted time, what I missed, and what to
   practice next. Compare my approach to the intended one and explain the
   difference.

## Rules

- Never start solving the problem unless I ask.
- Keep hints proportional - small ones first.
- Be honest, not flattering. If my solution is wrong, say why precisely.
- If I'm stuck for a long time, coach me on a strategy (try a smaller case,
  brute force first, draw it out) rather than just handing me the answer.

Help me prepare a conference talk: `[talk idea / topic / experience]`. The
goal is a submission that gets accepted and a talk that fits its slot, with
a real demo that survives live. Work through proposal, iteration, outline,
demo, and rehearsal, and verify each stage before moving on.

## Steps

1. **Define the proposal skeleton** - Capture the hook (why care now), the
   one takeaway (what the audience leaves knowing), and the audience fit
   (who, at what level, with what they already know). If you cannot state
   the takeaway in one sentence, the idea is not ready.
2. **Audit the fit** - Check the CFP: the conference's audience, the talk
   length, the format (lightning, 30/45/60 minute), and what previous
   accepted talks covered. Adjust depth and scope to match, and say how the
   talk fits the conference theme.
3. **Draft and stress the abstract** - Write the abstract and title, then
   critique them: is the hook sharp, does the takeaway survive the word
   budget, would the target audience click it? Revise at least once against
   that critique, keeping it within the CFP's word limit.
4. **Time the outline** - Build an outline calibrated to the slot: intro,
   main points with time each, demo, and a Q&A buffer. A spoken script of
   one to two words per second is about right; check the outline's total
   against the slot before writing slides.
5. **Plan the demo for failure** - Write the live-demo script and a fallback
   for every fragile step: pre-recorded capture, local fixtures, pinned
   dependencies, and a stated plan for what you say if the demo breaks.
   Never wing a live demo with no fallback.
6. **Rehearse against a rubric** - Run the talk once fully timed, then score
   it: did each section land in its budget, was the takeaway delivered, were
   transitions smooth, did the demo fit? Rehearse the two weakest spots and
   re-time.

## Verification

- [ ] The abstract fits the CFP word limit and states a concrete takeaway.
- [ ] The outline's total timed length fits the slot, including a Q&A buffer.
- [ ] Every live-demo step has a recorded or fixture fallback.
- [ ] At least one full timed run-through happened, and the issues from it
      are fixed or named.
- [ ] The talk's level matches the CFP's stated audience.

## Rules

- Never submit before the takeaway is stateable in one sentence.
- Never claim a fit with the slot without a timed run-through.
- Never plan a live demo step you cannot fall back from.
- Keep iteration real: each revision must address a named weakness, not be
  cosmetic word-shuffling.

Build a learning roadmap for the specified skill or goal. The output must be
a plan someone can follow and verify - projects that produce artifacts,
checkpoints that prove progress - not a list of courses.

## Steps

1. **Define the target precisely** - What does "learn X" mean concretely?
   ("Build and deploy a full-stack app with auth and tests", not "become a
   better developer".) Anchor to a real goal: a job requirement, a portfolio
   piece, or a task blocked at work.
2. **Assess the starting point honestly** - List what is already known vs
   missing. Verify claims against evidence (can you build a small thing right
   now?). Unknowns become early roadmap items.
3. **Sequence by dependency** - Order topics so each unlocks the next;
   front-load fundamentals only when they unblock projects. Cut anything not
   serving the stated goal, and say what was cut.
4. **Center it on projects** - Each phase is one small project that forces
   the new skill into use and leaves an artifact (repo, deployed app, post).
   Projects build on each other toward a capstone.
5. **Add verifiable checkpoints** - Per phase: what you can DO when done
   ("deploy an API with CI and meaningful test coverage"), how to self-test
   it, and the time budget. Include a stuck protocol: timebox, where to ask,
   how to decompose the problem.
6. **Budget realistically** - Hours per week times weeks, padded for life. A
   plan that survives contact with reality beats an ambitious one abandoned
   in week two.
7. **Schedule reviews** - Weekly retro questions (what shipped? what's
   blocked?) and permission to re-scope after each checkpoint instead of
   silently slipping.

## Output

A phased roadmap: goal statement, current-state assessment, phases with
projects/checkpoints/time estimates, review cadence, and the capstone.

## Rules

- Every phase must produce something runnable or publishable - passive
  consumption alone does not count as progress.
- No phase without a way to verify success; if you can't test it, restate it.
- Prefer depth on fewer things over surveying everything.

Help me build a portfolio-worthy project. I'll describe the idea; you help me
shape it into something scoped, real, and presentable - something I can
explain confidently and that demonstrates actual skill.

## What to do

1. **Shape the idea** - Turn my description into a concrete project: what it
   does, who it's for, and the 1–3 things that make it interesting. Push back
   on scope creep ("a full app with auth, payments, and notifications" is too
   much) and suggest the smallest version that's still impressive.
2. **Decide the stack** - Propose a stack I actually can build and explain,
   matching my stated skills. Favor boring, well-documented choices unless
   the project specifically wants something novel. Ask if you're unsure what I
   know.
3. **Make a roadmap** - Break it into milestones that each produce something
   working and demonstrable: MVP first (core feature works), then polish,
   then extras. Each milestone has a clear "done" definition and how I'll test
   it.
4. **Build it with me** - Implement milestone by milestone using good
   practices: git from day one (small commits), tests where they matter,
   README that explains the project, and a working setup for someone to clone
   and run.
5. **Make it presentable** - A README that sells it honestly: what it is, how
   it works (with real screenshots/usage), the interesting technical decisions,
   and what I'd do next. Help me write a short "about this project" blurb for
   my portfolio/README that's specific and true.

## Rules

- Keep me in the loop on decisions; don't silently build a different project
  than we agreed.
- Prefer code I can understand and explain over clever code I'd fumble when
  asked about it.
- No fake polish: no mock data pretending to be real, no claims the code
  doesn't support.
- The goal is a project I can talk about confidently - if we add complexity,
  make sure I can explain it.

Review my technical resume for `[role / company / level]`. The goal: honest,
specific feedback that helps me stand out as a strong candidate, not polished
mediocrity.

## What to do

1. **Check the first impression** - Is the summary/objective clear and
   specific? Does it say what kind of engineer I am and what I'm looking
   for in one sentence? Does the resume pass the 6-second scan test - can
   someone tell my specialty and seniority at a glance?
2. **Evaluate experience bullets** - For each role, check:
   - Does each bullet start with a strong verb describing what I did?
   - Does it quantify impact (users served, latency reduced, revenue
     generated, tests added)?
   - Does it describe the technical challenge, not just the task?
   - Is it specific enough that someone in the field would be impressed,
     or vague enough that it could describe anyone?
3. **Assess technical depth** - Does the skills section list actual
   technologies I can discuss in an interview, or buzzwords I've only
   read about? Is there evidence of depth (contributions, talks, side
   projects) beyond just listing tools?
4. **Check for honesty** - Flag anything that overstates my role or
   contribution ("led the team" when I was a junior contributor,
   "architected the system" when I implemented a spec). Recruiters
   verify these claims.
5. **Review formatting and clarity** - Is the layout scannable? Are there
   no typos, inconsistent formatting, or walls of text? Is it one page
   (early career) or two pages max (experienced)?
6. **Keyword alignment** - Compare the resume against the target job
   description. Are the key technologies and skills mentioned? Are there
   gaps that would cause it to be filtered out by ATS?

## Rules

- Never suggest adding skills I don't actually have - lying on a resume
  backfires in interviews.
- Never suggest vague improvements ("make it more impactful") without
  showing the specific rewrite.
- Never pad the resume with filler - every line must earn its space.
- If the resume is already strong, say what works and suggest only minor
  refinements rather than inventing problems.

Help me write a technical blog post about `[topic / project / experience]`.
The goal: a post that teaches something real, engages the reader, and
demonstrates technical depth without being inaccessible.

## Steps

1. **Understand the audience** - Who is this for? Adjust technical depth
   accordingly: beginner (explain concepts), intermediate (assume familiarity
   with basics), advanced (focus on nuances and trade-offs). Define the
   "one thing" the reader should take away.
2. **Find the story** - Every good technical post has a narrative, not just
   facts. Identify the hook: what problem did you solve, what did you learn,
   what surprised you, or what mistake did you make? Lead with the
   interesting part, not "In this post, I will discuss..."
3. **Outline the structure** - Use this order (adapt as needed):
   - Hook / problem statement (why should the reader care?)
   - Context (what was the situation before?)
   - Approach (what did you do and why?)
   - Technical details (how it works, with code/diagrams)
   - Results or lessons learned (what happened?)
   - Takeaways (what should the reader do differently?)
4. **Write the draft** - Write in a conversational but technically accurate
   voice. Use code examples that are real and runnable, not pseudocode.
   Explain the "why" behind decisions, not just the "what." Keep paragraphs
   short and use headers for scannability.
5. **Review for accuracy** - Verify every technical claim. Run every code
   example. Check that links resolve. If something is uncertain, flag it
   rather than guessing. A wrong technical detail destroys credibility.
6. **Polish** - Cut unnecessary words. Simplify complex sentences. Add
   transitions between sections. Ensure the post reads well end-to-end.

## Rules

- Never write a post that restates the official documentation without
  adding your own experience or perspective.
- Never include code examples you haven't verified work.
- Never use filler phrases ("It's worth noting that...", "It goes without
  saying...") - either say it or don't.
- If the topic is too broad, narrow it - a focused post on one specific
  lesson beats a shallow overview of everything.

Review the accessibility of `[component / page / feature]` in this repository.
The goal: ensure the UI is usable by people relying on keyboards, screen
readers, and assistive technologies, meeting WCAG 2.1 AA at minimum.

## Scope to cover

1. **Semantic HTML** - Check that elements use appropriate tags (button vs div,
   nav, main, heading hierarchy, lists). Flag div/span soup that should be
   semantic elements.
2. **Keyboard navigation** - Verify all interactive elements are focusable,
   focus order is logical, focus is visible, and no keyboard traps exist.
   Check for Escape to close modals, Tab/Shift+Tab navigation, Enter/Space
   activation.
3. **Screen reader support** - Check for meaningful alt text on images,
   aria-labels on icon-only buttons, aria-live regions for dynamic content,
   proper form labels, and that dynamic content announcements work.
4. **Color and contrast** - Verify text meets WCAG contrast ratios (4.5:1 for
   normal text, 3:1 for large text). Check that color is not the only way to
   convey information (error states, status indicators).
5. **Forms and inputs** - Verify every input has an associated label, error
   messages are programmatically associated with their fields, required fields
   are indicated, and fieldsets/groupings are used where appropriate.
6. **Motion and timing** - Check for respects-preference-of-reduced-motion,
   auto-playing animations with no pause control, and time limits without
   extensions.

## Method

1. **Read the actual markup** - Examine the HTML/JSX/template for each
   component. Do not guess from the visual output - read the DOM structure.
2. **Trace the keyboard path** - Walk through every interactive element in tab
   order. Verify each can be reached, activated, and escaped with keyboard
   alone.
3. **Cite specific instances** - For each finding, reference the exact file:line
   and the specific WCAG success criterion violated (e.g. 1.1.1, 2.1.1,
   4.1.2).
4. **Propose concrete fixes** - Show the code change needed, not just "add
   aria-label". Include the specific attribute or element swap.

## Rules

- Never report "could be more accessible" without specifying what fails and
  which WCAG criterion it violates.
- Never recommend aria attributes as a first resort when a semantic HTML
  element would be simpler and more robust.
- If the UI is already accessible, say so and list what was verified rather
  than inventing issues.
- Do not flag visual-only decorative elements (purely decorative images,
  ornamental dividers) as missing alt text.

Audit the architecture of this repository as a senior software architect.
Read-only: this produces a report, never diffs. Every claim must trace to a
file:line or a measured number - accuracy matters more than volume.

## Define the scope first

State all four before reading any code:

1. **Target** - Whole repo, or a specific module/directory/service? If the
   repo is large, propose the highest-value slice (core logic, public API
   surface, lines with the most ownership churn) and defend the cut.
2. **Platforms & stack** - Language(s), framework(s), build tooling, and
   whether this is a monorepo, a service mesh, a library, or an application.
3. **Inputs in scope** - Source, tests, build/config, scheduler and CI
   definitions, docs/ADRs. List what you are including.
4. **Out of scope** - Functional bug hunting, deep security and performance
   audits (they have their own prompts), and any code change. Audit-read only.

## What to produce

1. **Scorecard** - One score (0-10) per dimension below, plus a single Overall
   Architecture score. Anchor: 9-10 production-grade; 7-8 solid with specific
   weak spots; 5-6 functional but fragile; 3-4 needs rework; 0-2
   foundationally broken. Every score carries a file:line or measured
   justification - no bare numbers.

   Dimensions (non-overlapping - no finding is counted twice):

   1. Structure & modularity - component sizes, monoliths, god components,
      where to split/merge/relocate.
   2. Coupling & dependency direction - dependency direction, circular
      dependencies, hidden/tight coupling, boundary discipline.
   3. Abstractions & separation of concerns - poor or leaky abstractions,
      ownership clarity, accidental complexity.
   4. Duplication & dead code - duplicated or fragmented functionality;
      placeholder, obsolete, or redundant code.
   5. Maintainability & technical debt - how cheap change is, debt hotspots.
   6. Testing - coverage of critical paths, test health, what untested code
      risks.
   7. Documentation - architecture docs, README, drift between docs and
      behavior.
   8. Production readiness - error handling, security posture, performance
      risks, scalability, observability.

2. **Findings report** - Every finding, one template: Severity
   (Critical/Major/Minor), Evidence (file:line plus the reading that proves
   it), Impact (what breaks and who pays), Recommended fix (minimal first
   step, not a rewrite). Major/minor all get the same template - severity
   differs, detail does not.

3. **Architecture map** - The real boundaries: modules/packages/services,
   entry points, dependency direction, and any cycles. This is the shared
   picture the rest of the report hangs on.

4. **Top problems** - Up to ten, ranked, each traceable to a finding.

5. **Refactoring roadmap** - Prioritized: fix now (blocks current work or
   risks incidents), schedule (real cost, not urgent), accept and document.
   No big-bang rewrites; every entry names a first increment and how to
   verify it.

## Method

1. **Map first** - Identify the boundaries and dependency graph before judging
   any component. A component read in isolation is reliably misjudged.
2. **Measure before concluding** - Baseline the repo: largest files and
   functions, LOC per module, test counts and coverage on critical paths,
   build time. Prefer measured signals over adjectives.
3. **Read the actual code** - For each candidate finding, trace the calls in
   and out; confirm the coupling claim by reading both ends of the edge.
4. **Verify impact** - Keep only findings with an observable cost: a bug
   report touching the area, a slow step, repeated workarounds. Discard items
   with no demonstrated cost.
5. **Report, never fix** - Log findings only. Do not refactor, rename, or
   reformat.

## Verification

- [ ] Scope stated (target, platforms, inputs, out-of-scope) before any code
      was read.
- [ ] Every scorecard score carries a file:line or measured justification.
- [ ] Every finding uses Severity/Evidence/Impact/Fix, with evidence naming a
      concrete file:line.
- [ ] At most ten top problems, each traceable to a finding.
- [ ] Roadmap ordered by risk; every entry starts an increment, not a rewrite.
- [ ] Things swept and found clean are reported, not just the problems.
- [ ] No code, config, or docs were modified - the report is the only output.

## Rules

- Never modify, move, or delete code - this task produces a report only.
- Never report a finding without a file:line or measured trace; unprovable
  suspicions go in a separate "needs confirmation" list.
- Never count a problem in more than one dimension; each finding maps to
  exactly one.
- Never pad - five verified findings beat forty speculative ones.
- Never propose a rewrite; fixes must be incremental and verifiable.

Audit this repo as a senior software architect. Read-only: this produces a
report, never diffs. Every claim must trace to a file:line or measured evidence -
accuracy matters more than volume.

## Define the scope first

State all four before reading any code:

1. **Target** - Whole repo, or a specific module, package, service, or
   directory? If the repo is large, identify the highest-value boundaries to
   audit first and state the boundary.
2. **Platforms & stack** - Language(s), framework(s), runtime, package
   manager, and repo architecture (monorepo, microservices, standalone app, or
   library).
3. **Inputs in scope** - Source files, tests, build configurations, dependency
   manifests, documentation, and CI workflows.
4. **Out of scope** - Modifying code, formatting fixes, functional bug hunting,
   or speculative refactors. Read-only analysis.

## What to produce

1. **Scorecard** - Rate 0-10 for each dimension below, plus an Overall
   Architecture score. Anchor: 9-10 production-grade; 7-8 solid with specific
   weak spots; 5-6 functional but fragile; 3-4 needs rework; 0-2 foundationally
   broken. Every score must carry a file:line or measured justification:

   - Overall code quality
   - Architecture & system structure
   - Maintainability & technical debt
   - Modularity & boundary clarity
   - Cohesion & coupling
   - Separation of concerns
   - Duplication & redundancy
   - Testing & test health
   - Documentation & spec alignment
   - Error handling & resilience
   - Security posture
   - Performance & resource efficiency
   - Scalability
   - Production readiness

2. **Structural smells & boundaries** - Specifically identify:

   - Monoliths and overly large components
   - Systems, subsystems, modules, packages, services, and boundaries
   - Dependency direction and circular dependencies
   - God classes/functions/components
   - Poor abstractions and leaky boundaries
   - Tight coupling and hidden dependencies
   - Duplicated or fragmented functionality
   - Unclear ownership/responsibilities
   - Dead, obsolete, placeholder, or redundant code
   - Architectural inconsistencies and accidental complexity
   - Areas that should be split, merged, relocated, or redesigned

3. **Findings report** - For each major issue give severity (Critical, Major,
   Minor), evidence (file:line citation and reading), impact (what breaks, what
   slows down, or what risk is introduced), and recommended fix (minimal first
   increment).

4. **Top 10 problems** - Ranked list of the top 10 problems across the
   repository, each traceable to a specific finding.

5. **Refactoring roadmap** - Prioritized: fix now (immediate risk or blocker),
   schedule (technical debt with real maintenance cost), accept and document.
   Every item names a concrete first increment. Do not modify code.

## Method

1. **Map boundaries first** - Identify the top-level packages, modules, entry
   points, and dependency graph before evaluating individual files.
2. **Measure before concluding** - Baseline file sizes, function lengths,
   dependency relationships, and test presence. Prefer measured facts over
   impressions.
3. **Trace the code** - For each candidate finding, trace callers and callees
   to confirm coupling, leakage, or duplication.
4. **Verify impact** - Keep only issues with an observable maintenance or
   runtime cost.
5. **Report only** - Log findings with evidence. Do not edit, refactor, or
   delete code.

## Verification

- [ ] Scope (target, stack, inputs, out-of-scope) stated before code was
      inspected.
- [ ] 0-10 scorecard provided for all dimensions, each backed by file:line
      citations or measurements.
- [ ] Structural smells and boundaries evaluated across all 11 target areas.
- [ ] Every major finding uses severity, evidence, impact, and recommended fix
      with concrete file:line evidence.
- [ ] Top 10 problems ranked and tied to documented findings.
- [ ] Refactoring roadmap prioritized with verifiable increments.
- [ ] No code was modified - the audit is strictly read-only.

## Rules

- Never modify, delete, or reformat code - this produces a report only.
- Never report a finding or score without file:line evidence or a verifiable
  trace.
- Never pad findings - verified architectural facts beat speculative lists.
- Never propose big-bang rewrites; fixes must be incremental and verifiable.
- Never accept "done" without satisfying every deliverable in this spec.

Review the performance of `[file / module / endpoint]` in this repository.
Find real inefficiencies and propose concrete fixes backed by evidence.

## Scope to cover

1. **Algorithmic complexity** - Identify O(n^2) or worse operations where O(n)
   or O(n log n) is achievable: nested loops over collections, repeated
   lookups in unindexed structures, unnecessary sorting.
2. **N+1 queries and calls** - Find patterns where a loop triggers individual
   database queries, API calls, or file reads that could be batched.
3. **Blocking I/O in hot paths** - Identify synchronous file reads, network
   calls, or database queries in request handlers or tight loops where async
   or batching would help.
4. **Memory and allocation** - Spot unnecessary copies of large data structures,
   string concatenation in loops, collections that grow unbounded, or objects
   retained longer than needed.
5. **Caching opportunities** - Identify repeated expensive computations or
   lookups that could be memoized or cached, and where the cache should
   invalidate.
6. **Frontend-specific** - Re-renders caused by unstable references, missing
   memoization, unoptimized images, large bundle sizes, layout thrashing,
   or excessive DOM manipulation.

## Method

1. **Read the code path** - Trace the execution from entry point to completion.
   Identify every operation and its cost. Do not guess - read the actual code.
2. **Cite evidence** - For each finding, reference the specific file:line and
   explain the performance impact with concrete numbers where possible (query
   count, loop iterations, memory size).
3. **Propose minimal fixes** - Suggest the smallest change that addresses each
   issue: an index, a batch query, an early exit, a memoization cache. Follow
   the repo's existing patterns.
4. **Estimate impact** - Rate each finding as High/Medium/Low impact based on
   how frequently the code path runs and how much time it saves.

## Rules

- Never flag something as slow without explaining why it is slow and what
  makes it measurable.
- Never recommend premature micro-optimizations (e.g. replacing a clear loop
  with a one-liner) unless profiling proves it matters.
- If the code is already performant, say so and stop - do not invent problems.
- Always verify that the proposed fix preserves correctness.

Review this code with a security focus. The author has already had a
functional review - your job is to find the ways an attacker or a bad input
could abuse it. Verify everything; don't flag theoretical risks without a
real path.

## What to hunt for

1. **Injection & shell** - User input reaching SQL/NoSQL queries, shell
   commands, URLs, templates, or deserializers. Trace input from source to
   sink before flagging.
2. **Authn/authz** - Missing or bypassable checks, IDOR (using another user's
   ID without ownership checks), privilege escalation, hardcoded/weak
   credentials, secrets in code.
3. **Web & network** - XSS (esp. where user content is rendered), CSRF, SSRF,
   open redirects, insecure headers/CSP, missing TLS, trusting attacker-controlled
   URLs or hosts.
4. **Data handling** - Sensitive data logged or returned in responses,
   over-permissive CORS, secrets in error messages, caching of private data,
   insecure deserialization.
5. **Dependencies & config** - New dependencies with known vulnerabilities,
   unsafe defaults, debug mode, permissive permissions.

## Method

- Read the actual diff and the surrounding code. For each concern, show the
  input-to-sink path with `file:line`. If you can't show the path, mark it as
  "worth checking" rather than a finding.
- Confirm your claims: run the code or tests if that helps, read configs, and
  check docs.
- Rank findings by real exploitability and severity. A high-severity issue
  with no reachable path is less important than a medium one an attacker can
  actually hit.

## Output

A short report: confirmed findings (path + severity + fix), then
lower-confidence items to double-check. Separate blocking security issues from
nice-to-harden. No fluff, no duplicates.

## Rules

- Never run destructive or write operations against real systems during review.
- Don't fix the code unless asked - report the findings and proposed fixes.
- Never dismiss a real issue because it's "just" a demo/assignment; say so
  but still report it.

You have been dropped into a repository you have never seen. Before you take on
any task, run the onboarding protocol below and end with a compact, verified
working model in your own context: enough to run it, change it, test it, and
locate anything in it on demand. Do this without asking the user anything.
Everything you need is in the repo; where the code is ambiguous, record the
ambiguity as an open question with the evidence and a named way to resolve it,
and move on.

## Define the scope first

Using only evidence you can see, state your scope in one line before reading
anything:

1. **Depth** - If the user attached a task, read the paths it touches at
   working depth and hold everything else at orientation depth. If there is no
   task, aim for operational completeness (the model in the next section).
2. **Highest-value slice** - In a large repo, pick the slice the task needs, or
   the core logic of the system if no task is attached. Do not onboard
   vendored, generated, or third-party code.
3. **Out of scope** - Deep review, refactoring, and fixes are out of scope.
   Onboarding produces a model, not changes.

Treat each as a decision you can revise, not a question for the user.

## What to produce

End with a **living in-context model** in exactly this shape, as bullets and
file:line anchors, never pasted file bodies:

1. **Verified stack** - One line per layer (language, runtime, framework,
   build tool), each citing the manifest or lockfile. If a layer cannot be
   verified, say so instead of guessing.
2. **Entry-point map** - Each entry point (CLI, server, worker, script,
   tests) as a path with a line reference and one line on what it does.
3. **One traced journey** - The most representative path a user or system
   takes: entry point, dispatch to core logic, storage or external call,
   response. Every hop carries a file:line reference.
4. **Exact run, test, and lint commands** - Each command cites the manifest
   script, Makefile, CI workflow, or README line that proves it exists.
5. **Conventions and gotchas** - Required env vars, config files, setup,
   extension points, and unusual patterns, each labeled documented or
   observed.
6. **Open questions** - Only what the code cannot answer, each with the
   evidence that made it ambiguous and the one probe that would resolve it.
7. **Context file (conditional)** - Only if the repo has a native ignored
   scratch area (a `tmp/` or `scratch/` directory, or an agent-owned temp
   directory) and a later session could reuse it: a file of no more than
   60 terse lines, refreshed on later sessions. Never write into tracked
   source, docs, or config.

## Method

Run the phases in order. Each has an exit condition; do not skip a phase to
save steps, and do not pad one with reads that close nothing.

1. **Skeleton from cheap signals** - Before opening any source file, form the
   shape of the repo from the cheapest evidence: the tree (two or three
   levels), git state, then manifests and configs (`package.json`,
   `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `tsconfig`,
   `*.config.*`, `Makefile`), then CI workflows, then the README, which you
   treat as a hypothesis until proven. Read directories before files, and
   index files before the modules they point at. Exit: a hypothesis map with
   named entry points to verify, and no source read yet.
2. **Verify, narrow, batch** - Prove each hypothesis with a file you actually
   opened. Pull versions from lockfiles, never README prose. Find symbols with
   grep before opening whole files, and batch independent reads into a single
   parallel tool call. No more than five whole-file source reads before your
   first claim is verified; prefer partial reads and grep the rest. Exit: every
   claim has a citation or sits in open questions.
3. **Trace one journey** - Route through the framework's registration points
   (routes, handlers, commands, events) rather than trusting file names. Cite
   at least three hops that resolve when you re-open them. Exit: a path a user
   or system actually takes, end to end.
4. **Extract commands and conventions** - Derive run, test, and lint commands
   from the repo's own tooling and prove each in a manifest, Makefile, CI
   workflow, or README. Label conventions documented or observed. Exit: every
   command you report carries proof it exists.
5. **Compress the model** - Eliminate exploration that no longer earns its
   place, and keep the model under 100 terse lines at all times. Open
   questions stay; unconfirmed speculation does not. Exit: the model is the
   smallest set of confirmed claims that makes the next task faster.
6. **Prove it once, cheaply** - Execute the cheapest command that exercises
   the model: a build, the test suite, or a script you traced. If the output
   contradicts the model, correct the model and re-run. Exit: one real command
   has run and its output is logged in your context, not asserted.

## Verification

Before declaring the model complete, confirm each of these:

- [ ] The skeleton pass ran before the first source read.
- [ ] No more than five whole-file source reads preceded the first verified
      claim; the rest of the map came from grep and partial reads.
- [ ] Every stack, architecture, and entry-point claim points at a config,
      manifest, or source path you actually opened, and versions come from
      lockfiles.
- [ ] At least one journey is traced with at least three file:line hops that
      resolve.
- [ ] The run, test, and lint commands you report exist in the repo's own
      tooling, and you executed at least one of them with output recorded.
- [ ] The living model is under 100 terse lines, contains no pasted file
      bodies, and every convention claim is labeled documented or observed.
- [ ] No writes landed in tracked source, docs, or config; a context file was
      written only into a native ignored scratch area.
- [ ] Every open question names its evidence and the one probe that would
      resolve it.

## Rules

- Never ask the user. Infer from the repo; unresolvable ambiguity goes to open
  questions with the evidence attached.
- Spend tokens like they are billed: no lockfile dependency trees, generated
  output, or binary and media files unless a task needs them.
- A file:line anchor costs less than a pasted body: cite, never transcribe.
- Never claim a command ran unless you ran it and saw the output, and never
  cite a file you have not opened.
- Treat the README as a claim to verify, not a source of truth.
- Stop at diminishing returns: two consecutive targeted probes that add no new
  confirmed claim mean onboarding is done.
- The goal is not to understand everything; it is to be ready to act on
  evidence.

Design a REST API for `[feature / domain]`. The goal: a consistent, documented,
and validated API that other developers can understand and integrate with
confidently.

## Steps

1. **Understand the domain** - Read the existing codebase, data models, and any
   existing API routes. Identify the resources, their relationships, and the
   operations needed. Do not design in a vacuum - ground the API in what the
   code already does.
2. **Define resources and routes** - Use noun-based URLs for resources
   (`/users`, `/projects`), HTTP verbs for operations (GET, POST, PUT, PATCH,
   DELETE), and consistent nesting depth (max 2 levels). Follow the existing
   API conventions in the codebase.
3. **Design request/response schemas** - Define typed request bodies, query
   parameters, and response shapes. Use consistent error response formats
   across all endpoints. Include pagination for list endpoints.
4. **Add validation and error handling** - Specify input validation rules,
   meaningful error messages, and proper HTTP status codes. Document edge
   cases: what happens on conflict, not-found, or unauthorized.
5. **Write the OpenAPI spec** - Produce a valid OpenAPI 3.x YAML/JSON spec
   covering all endpoints, schemas, and error responses. Include examples for
   each endpoint.
6. **Verify** - Check the spec validates cleanly (use `swagger-cli validate` or
   equivalent). Confirm routes don't collide and naming is consistent
   throughout.

## Rules

- Never invent endpoints that don't map to actual data or operations in the
  codebase.
- Never use verb-based URLs (e.g. `/getUser`) - use HTTP verbs instead.
- Keep the API consistent: if one list endpoint uses `?page=`, all should.
- If the codebase already has API conventions, follow them exactly - do not
  introduce a parallel style.

Integrate the `[API name / endpoint docs]` into this repository's codebase.
Read the actual API docs and the existing code before writing anything.

## Steps

1. **Read the API** - Understand the endpoints you need: request/response
   shapes, auth, rate limits, pagination, and error semantics. Read the actual
   docs, not just a guess from the URL.
2. **Match the codebase** - Use the existing HTTP client, error handling,
   logging, and config patterns. Do not introduce a new HTTP library unless
   the existing one can't do the job.
3. **Types & boundaries** - Define typed request/response models (or equivalent)
   matching the API contract. Keep the integration behind a small boundary so
   callers don't depend on the wire format.
4. **Handle the real world** - Timeouts, retries with backoff for transient
   failures, clear errors for 4xx/5xx, pagination, and rate-limit handling.
   No infinite retries, no swallowed errors.
5. **Auth & config** - Keep credentials in config/env/secrets, never hardcoded.
   Follow the repo's existing secret-handling conventions.
6. **Test** - Write tests for the integration's behavior: success path, error
   mapping, retries, and edge cases (empty responses, malformed payloads).
   Use the repo's existing test doubles (mocks/fixtures/cassettes), and
   confirm the test suite runs green.

## Rules

- Never paste sample code from API docs into the codebase as-is - adapt it to
  the repo's conventions.
- Verify your assumptions about the API against real responses where possible.
- If the docs and the live API disagree, flag it and verify rather than
  guessing which is right.

Build a command-line tool for `[what the tool does]` in this repository.
The goal: a CLI a seasoned user can run without surprises - correct exit
codes, a clean `--help`, sane behavior under pipes and scripts, and a test
suite that covers the logic directly.

## Steps

1. **Read the project's CLI conventions** - Check whether the repo already
   uses a CLI framework (argparse, click, cobra, commander, clap) and which
   entry points already exist. Mirror the existing style: how options are
   declared, how errors are printed, how the tool is installed and run.
2. **Design the interface first** - Write down the flags and arguments
   before coding: required vs optional, defaults, aliases, and conflict
   rules. Prefer a small surface and explicit flags over positional magic.
   There should be one obvious way to do each thing.
3. **Separate parse from run** - Structure the code as parse -> run -> render
   so the core logic lives in a plain function a test can call directly. The
   entry point is a thin wrapper: parse argv, call the function, print the
   result, map failures to exit codes.
4. **Be defensive about input** - Read stdin only when the interface says so;
   never block waiting on a pipe the user never opened. Handle missing files,
   invalid values, empty input, and non-UTF8 data with a clear user-facing
   message instead of a traceback.
5. **Make exit codes meaningful** - Exit 0 on success. Use a distinct
   non-zero code per failure class (usage, runtime, input) and document each.
   `--help` and `--version` exit 0; an unknown flag exits with the platform's
   usage-error code where one exists. Honor `SIGPIPE` so a closed pipe does
   not surface as an error.
6. **Respect TTY vs pipe** - Detect a TTY before printing colors, spinners,
   or progress bars, and degrade to plain text when stdout is not a terminal.
   Never write control characters or ANSI escapes into a piped stream.
7. **Verify** - Run the tool against real and edge inputs: empty stdin, very
   large input, invalid flags, missing arguments, unicode paths. Check that
   exit codes match the spec, `--help` renders correctly, and piping into
   another command terminates cleanly. Run the repo's test suite and
   linters.

## Verification

- [ ] Every exit code is documented and reachable from a test.
- [ ] Piping output into another command works and does not hang or error on
      a closed pipe.
- [ ] A bad flag or missing argument prints a usage message, never a traceback.
- [ ] The core logic is covered by tests that call the function directly, not
      only through subprocesses.

## Rules

- Never print a raw traceback to the user; format errors as `tool: message`.
- Never use global mutable state; keep the run function pure and injectable.
- Never add a flag you cannot document and test.
- Match the repo's existing CLI conventions over your preference.

Migrate `[source code / module / feature]` from `[current stack/version]` to
`[target stack/version]`. The rule: **behavioral parity at every step** - the
application must work before, between, and after the migration.

## Scope to cover

1. **Inventory** - Map every file, function, API endpoint, and configuration
   that needs to change. Identify shared code that does not need migration.
   Count the surface area so the effort is predictable.
2. **Deprecation and breaking changes** - Read the target version's migration
   guide and changelog. List every breaking change that affects this codebase
   with the specific file and line impacted.
3. **Risk assessment** - Identify the riskiest parts of the migration:
   dependencies that may not have compatible versions, behavioral differences
   that could cause silent bugs, and areas with weak test coverage.

## Method

1. **Establish a safety net** - Before changing anything, ensure the test suite
   passes on the current version. If coverage is thin, add characterization
   tests for the critical paths first - these capture current behavior so you
   can verify parity later.
2. **Migrate incrementally** - Work in small, independently deployable steps:
   migrate one module, one route, or one file at a time. Each step must leave
   the application in a working state. Never do a "big bang" rewrite.
3. **Handle dependencies first** - Upgrade or replace libraries that the
   migration depends on before touching application code. Verify each
   dependency update independently.
4. **Adapt the code** - Translate syntax, patterns, and APIs to the target
   stack. Follow the target stack's idioms, not a literal translation. Remove
   dead code left behind by the migration.
5. **Verify parity at each step** - After each incremental change, run the
   full test suite plus any manual smoke tests. Compare behavior against the
   baseline. If something changed intentionally, document the reason.
6. **Clean up** - Remove old code, old dependencies, old config, and migration
   scaffolding. Update documentation, README, and CI to reflect the new stack.

## Rules

- Never migrate everything at once and hope it works - small steps only.
- Never change behavior during a migration unless explicitly scoped as part of
  the migration.
- If a migration step requires more than 200 lines of changes, split it
  further.
- If the test suite does not pass after a step, stop and fix it before
  continuing - never stack broken changes.
- If a dependency has no compatible version for the target, flag it early
  rather than hacking around it.

Design a database schema for `[feature / domain]`. The goal: a clean,
normalized data model that supports the required queries without over-engineering.

## Steps

1. **Understand the requirements** - Read the feature spec, existing data
   models, and any current database schemas in the codebase. Identify the
   entities, their attributes, and relationships (one-to-one, one-to-many,
   many-to-many). Do not design tables that duplicate what already exists.
2. **Define tables and columns** - Name tables and columns consistently with
   the existing codebase conventions (snake_case, singular/plural). Choose
   appropriate data types and nullable vs required constraints. Include
   `created_at`/`updated_at` timestamps where the repo uses them.
3. **Set up relationships** - Define foreign keys, junction tables for
   many-to-many relationships, and ON DELETE/UPDATE behavior. Ensure referential
   integrity at the database level, not just in application code.
4. **Plan indexes** - Identify columns used in WHERE, JOIN, and ORDER BY
   clauses. Add indexes for expected query patterns. Avoid over-indexing:
   every index has a write cost.
5. **Normalize appropriately** - Apply normalization (3NF) to eliminate
   redundancy, but denormalize deliberately where read performance requires it
   (and document the trade-off).
6. **Write the migration** - Produce a migration script that creates the schema
   incrementally: CREATE TABLE, then ALTER for foreign keys and indexes. Follow
   the repo's existing migration tooling and conventions.
7. **Verify** - Run the migration against a test database. Confirm the tables
   create cleanly, constraints fire correctly, and sample queries work.

## Rules

- Never drop or rename columns in a migration without a backward-compatible
  expand-migrate-contract plan.
- Never add indexes on every column "just in case" - prove the query pattern
  needs it.
- If the existing schema has conventions (naming, soft deletes, audit columns),
  follow them exactly.
- Do not design for scale you don't need yet - a clean schema beats a
  prematurely optimized one.

Review or implement the datetime handling in this task. Timezone bugs are
among the most common production defects and are almost never caught by a
"looks right on my machine" check; treat every date/time value as a trap
until proven otherwise.

## Steps

1. **Store UTC, render local, always** - Persist and pass around timestamps
   in UTC (or a fixed offset like Unix epoch millis); convert to the user's
   local timezone only at the display/render boundary. Never store a
   "local" timestamp without its offset.
2. **Handle DST transitions explicitly** - Identify any logic that adds
   durations to a local time (e.g. "add 1 day") and confirm it survives a
   spring-forward/fall-back transition; use timezone-aware date-math
   libraries rather than naive arithmetic on wall-clock time. Flag
   ambiguous local times (the repeated hour during fall-back) instead of
   picking one silently.
3. **Parse untrusted date input defensively** - Never trust an
   unconstrained free-text date format from users or external APIs; validate
   against expected formats, reject or explicitly flag ambiguous inputs
   (e.g. `01/02/2026`, day-first vs month-first), and record the assumed
   timezone when the input doesn't specify one.
4. **Get durations and calendar math right** - Distinguish elapsed duration
   (a fixed number of seconds) from calendar duration ("add 1 month", which
   varies in length); use business-day math (skipping weekends/holidays)
   only where explicitly required, and state which holiday calendar applies.
5. **Write property tests around clock changes** - Test date-math functions
   across a DST boundary, a leap year/leap second edge, a month-end rollover
   (Jan 31 + 1 month), and a UTC offset that isn't a whole hour (e.g.
   India's UTC+5:30) - these are exactly the cases naive implementations get
   wrong.

## Rules

- Never format or compare a "naive" datetime (no timezone attached) against
  a timezone-aware one; make the mismatch a type error where the language
  allows it.
- Never hardcode a specific timezone offset as a constant; timezones and
  their offsets change (DST rules, political redefinitions) - use a
  timezone database, not a fixed number.
- If a date's true intended timezone is ambiguous from context, ask or
  document the assumption instead of guessing UTC vs local silently.

Debug the reported problem in this repository. Work systematically - do not
guess-and-patch. Follow these steps in order.

## Steps

1. **Reproduce** - Reproduce the bug yourself. If you can't, get the exact
   reproduction steps, inputs, and environment from the report, then try
   harder (check versions, config, seed data). A bug you can't reproduce is a
   bug you can't fix - say so rather than guessing.
2. **Isolate** - Narrow the failure to the smallest input and code path.
   Use `git bisect` if a recent change introduced it. Read the relevant code
   and trace the data flow to find where behavior diverges from intent.
3. **Root cause** - State the root cause precisely, with evidence (file:line).
   Distinguish root cause from symptom. If there are multiple suspects, rank
   them and test them rather than listing everything as "maybe".
4. **Fix** - Make the smallest fix that addresses the root cause without
   breaking existing behavior. Follow repo conventions. Do not band-aid the
   symptom or add speculative handling.
5. **Regression test** - Add or update a test that fails on the old code and
   passes on the fix. If the bug can't be tested, say why and verify manually.
6. **Verify** - Run the full test suite and the repo's checks. Confirm the
   original reproduction no longer reproduces.

## Rules

- Never claim a fix works without running it.
- If you can't find the root cause after genuine effort, report what you've
  ruled out and what you'd try next - do not ship an unverified patch.
- Flag any pre-existing bugs you notice while debugging as notes, don't fix
  them silently.

Set up a complete development environment for this repository from scratch.
The goal: a new contributor can clone the repo and be productive in minutes,
not hours.

## Steps

1. **Read the existing docs** - Check README.md, CONTRIBUTING.md, Makefile,
   docker-compose.yml, .tool-versions, .nvmrc, .python-version, or any
   setup-related files. Understand what the project expects before guessing.
2. **Install dependencies** - Run the actual install commands for the language
   runtime, package manager, and all dependencies. Use version managers (nvm,
   pyenv, rbenv, asdf) where the repo specifies them. Pin versions to match
   the repo's lockfiles.
3. **Configure tooling** - Set up linters, formatters, pre-commit hooks, and
   editor configs as the repo defines them. Verify each tool runs without
   errors.
4. **Set up services** - Start any required databases, caches, message brokers,
   or emulators (via docker-compose, local installs, or cloud sandboxes).
   Verify they accept connections.
5. **Build and run** - Execute the full build pipeline (compile, transpile,
   bundle). Run the application and confirm it starts without errors. Hit a
   health endpoint or open the UI to verify it works.
6. **Run the test suite** - Execute the full test suite. Fix any environment-
   related failures (missing env vars, wrong versions, unconfigured services).
   All tests should pass on a fresh setup.
7. **Document gaps** - If anything required manual intervention, undocumented
   steps, or workarounds, update the README or CONTRIBUTING with the fix.

## Rules

- Never skip steps or assume "the user will figure it out" - do every step
  end-to-end.
- Never install global packages that conflict with the repo's pinned versions.
- If the setup instructions in the README are wrong or incomplete, fix them
  rather than working around them.
- Verify every tool and service actually works, not just that it installed
  without error.

Design and apply a consistent error handling strategy for `[component or
service]` in this repository. The goal: no bare try/catch, no swallowed
errors, no unhandled crash on a path a user can hit. Inspection here means
reading code, not trusting it.

## Steps

1. **Read the existing conventions** - Find how this repo currently handles
   errors: exception types or error classes already in use, a logging library,
   response envelopes for APIs, retry utilities, and where errors are caught
   today. Mirror the existing style unless it is the problem. Note every catch
   that swallows the error or logs without context.
2. **Map the failure modes** - Enumerate every way this code can fail:
   transport and timeouts, persistence, validation and authorization, bad
   inputs, and resource limits. For each, name where it surfaces in code and
   what happens to the caller today.
3. **Define the policy** - Write one small policy before touching code:
   which failures are recoverable (retry with backoff and an idempotency
   guard), which are fail-fast (crash loudly so nothing silently drops), and
   which map to a user-visible error message. Distinguish programming errors
   from expected failures; the first are bugs, the second are control flow.
4. **Type the errors** - Introduce a small set of typed errors (framework
   exception or error subclasses) so callers branch on intent, not on message
   text. Carry structured context with each error: operation, resource,
   retryable flag, and a stable code for logs and monitors.
5. **Implement the smallest change** - Route each catch site through the
   policy. Add retries only where the operation is idempotent and the failure
   is transient. Never wrap a generic catch in silence: log the full context,
   then rethrow or map to a clean failure for the caller.
6. **Surface the right thing** - The user-facing layer shows a controlled
   message and a meaningful status; the internal layer records the stack and
   context. Never leak internals (SQL, stack traces, secrets) into what the
   user sees.
7. **Verify by injection** - Prove the policy, do not assert it. Force each
   failure mode (point a config at a dead endpoint, close a pool, pass bad
   data) and confirm the log line contains enough to debug, the retry behaves
   with backoff, and the user path returns the intended result. Show the
   before and after output.

## Rules

- Never add a catch block that swallows the error or logs without context.
- Never guess which failures can happen: find the failure sites in the code
  and list them before deciding the policy.
- Keep the policy close to the code it governs, not a page of theory elsewhere.
- No unrelated edits: this PR leaves the surrounding behavior unchanged unless
  a path was actually erroring silently.

## Verification

Run the repo's test suite and paste the output. Then list, with evidence, the
failure modes you injected and what each produced (log line, retry behaviour,
user-visible result). Confirm no error path exists that catches and ignores.

You are implementing a feature in this repository. Work end-to-end: understand
the requirement, design a minimal solution that fits the existing
architecture, implement it, verify it, and leave the codebase clean. Never
guess - read the relevant code first and verify every claim you make.

## Steps

1. **Understand** - Read the feature request/issue carefully. Read the code
   this touches: the files, their callers, and the surrounding tests. Ask
   clarifying questions if the requirement is ambiguous or conflicts with the
   existing design.
2. **Plan** - State your plan before writing code: the files you will change,
   what each change does, the edge cases you'll handle, and how you'll verify.
   Do not start editing until the plan is agreed.
3. **Design to fit** - Follow the repo's existing patterns, conventions, and
   architecture. Do not introduce a new library, pattern, or directory unless
   it's clearly warranted - prefer the boring, idiomatic option.
4. **Implement** - Write the smallest change that satisfies the requirement.
   Handle edge cases (empty input, missing data, errors, timeouts). Do not add
   speculative features or refactor unrelated code.
5. **Test** - Add or update tests that assert the actual behavior, including
   the key edge cases. Run the full test suite plus lint, format, and type
   checks using the repo's own tooling (check `pyproject.toml`, `package.json`,
   `Makefile`, CI workflows, or README). Fix whatever breaks.
6. **Verify the behavior** - Exercise the feature as a user would where
   practical, not just through mocked paths.
7. **Document** - Update README/CHANGELOG only if the feature changes user
   behavior or setup. Keep it accurate and in the repo's voice.
8. **Self-review** - Re-read your diff as a reviewer: is the fix correct, are
   the tests meaningful, is there anything dead, duplicated, or confusing?

## Rules

- Never modify unrelated code. If you find a pre-existing bug, flag it as a
  note instead of fixing it silently.
- Never leave commented-out code, debug prints, or TODOs you created.
- Verify before claiming: run the commands, don't assume they pass.
- If a step turns out to be harder than planned, stop and report rather than
  hacking around it.
- Commit in small, logical commits following the repo's commit convention
  (check `git log`), and only when the work is verified.

Build a detailed understanding of this repository. Produce a report that a
new team member could use to navigate the codebase on day one. Verify
everything against the code, lockfiles, and config - do not paraphrase the
README.

## Define the scope first

Before reading code, state:

1. **What you need to understand** - Clarify the focus: full repo overview, a
   particular subsystem, the data flow for a specific feature, or something
   else. If the request is broad, pick the highest-value slice and say so.
2. **What depth** - Quick orientation (stack + entry points) or deep dive
   (data flow, conventions, extension points)? State the level explicitly.
3. **What is out of scope** - Exclude anything not relevant to the request.

Do not begin reading until the scope and depth are defined.

## What to produce

1. **What it is** - One or two sentences: what the project does and who it is
   for. Confirm with the README and with real code, not just the repo name.

2. **Tech stack, verified** - Languages, frameworks, runtimes, package/build
   tooling, and the versions that matter. Pull these from lockfiles, manifests,
   and config files - not from README claims or guesses. If versions cannot be
   determined, say so.

3. **Architecture, with evidence** - The high-level shape: how the code is
   organized (monolith, services, packages, monorepo), the entry points (main,
   CLI, server, worker, script), and how the major pieces communicate. For each
   structural claim, cite a file, directory, or function that proves it.

4. **Key data flow** - Walk one or two realistic user journeys through the code:
   entry point → core logic → storage or external calls → response. Cite
   file:line for each hop. If multiple paths exist, pick the most representative
   and note the alternatives.

5. **Conventions and gotchas** - Things a newcomer will trip on: unusual patterns,
   required env vars, config files, build and test setup, extension points, and
   known quirks. Distinguish documented conventions from observed behavior.

6. **How to run it** - Exact commands to install dependencies, run, and test.
   Verify against the README, Makefile, scripts/, package.json/pyproject.toml,
   and CI workflows. If a command cannot be verified, say so.

7. **Open questions** - List anything that could not be confirmed from the code,
   and what would resolve it (e.g. a missing env var, an undocumented script,
   a dependency version that could not be read).

## Method

1. **Read the top-level structure** - Start with the root: manifest files,
   package/dependency configs, build scripts, CI workflows, and any
   documentation that describes the architecture. Form initial hypotheses.

2. **Form hypotheses, then verify** - For each structural claim (e.g.
   "this is a React app with a Node backend"), find the file or config that
   proves it. If a hypothesis cannot be confirmed, mark it as an open question.

3. **Trace a real journey** - Pick a concrete flow a user or system would take,
   and read the actual code path end to end. Cite file:line for each step.

4. **Inspect the test suite** - Read how the project tests itself. The test
   layout and patterns often reveal conventions and architecture more clearly
   than the source alone.

5. **Check the CI and scripts** - Read the workflows and helper scripts to
   understand how the project is built, tested, and deployed. These often
   expose requirements and gotchas that source code alone does not.

6. **Summarize with citations** - Produce the report above, with file:line
   references for every structural claim. No claim without evidence.

## Verification

Before reporting the understanding complete, confirm each of these:

- [ ] Every structural claim (stack, architecture, entry points) is backed by a
      file, config, or function citation.
- [ ] Versions and dependencies are read from lockfiles or manifests, not
      inferred from the README.
- [ ] At least one real data flow is traced end to end with file:line citations.
- [ ] Run commands are verified against the project's actual tooling (README,
      Makefile, scripts/, CI, manifest), not invented.
- [ ] Anything that could not be confirmed is listed as an open question, not
      stated as fact.
- [ ] The report distinguishes documented conventions from observed behavior.

## Rules

- Read the code. For every structural claim, point to a file or function that
  proves it.
- If the README is wrong or stale, say so and rely on the code.
- Be concise and concrete. No filler like "this project is built with modern
  best practices".
- State scope and depth before reading. Do not attempt the whole repo plus a
  deep dive in one pass unless the request is small.
- If something cannot be determined from the repository, say what is missing
  and how to find it - do not guess.

You are my pair-programming partner on this repository. We work in small,
explainable steps. You are allowed to read code, search, and run commands, but
you must not take large or surprising actions on your own.

## How we work

1. Before each change, tell me the one-line plan and what files it touches. If
   it's more than a small edit, wait for my go-ahead.
2. Write code in small chunks. After each chunk, briefly explain what you did
   and why, in plain language. Don't lecture - a couple of sentences.
3. Ask before doing anything destructive or irreversible: force pushes, branch
   deletion, mass renames, dependency installs, or anything outside the
   current task.
4. When you don't know something, say so and read the code to find out rather
   than guessing. Show your evidence (file:line) when you make a claim about
   how the code behaves.
5. After a piece of work is done, run the relevant tests/checks and show me the
   result before moving on.

## Ground rules

- Keep the existing code's style and conventions. No unrelated refactors.
- If you spot a better approach mid-task, mention it once and let me decide -
  don't silently change direction.
- No fluff: no "great question!", no summarizing what I already said. Just do
  the work and talk when there's something worth saying.

Refactor the code I point you at in this repository. The goal is cleaner,
more maintainable code with **identical external behavior**. Treat the test
suite as the contract.

## Method

1. **Read first** - Understand the code and its callers before touching
   anything. Note every place the behavior is observable (return values,
   side effects, errors, I/O).
2. **Establish a safety net** - If the code lacks good tests, write
   characterization tests that lock in current behavior first. Get them
   passing before refactoring.
3. **Small steps** - Refactor in small, behavior-preserving increments.
   After each step, run the tests. If tests fail, understand why - don't
   "fix" tests to match new behavior unless the behavior change is intended
   (and then say so explicitly).
4. **Keep the diff honest** - Do not mix refactoring with feature work.
   No formatting-only churn mixed into a logic change. No renaming of public
   APIs or changing signatures unless asked.
5. **Finish clean** - Remove dead code you created, keep naming consistent
   with the repo, and run the full suite plus lint/format/type checks at the
   end.

## Rules

- Never refactor for its own sake. Every change should have a reason you can
  state in one sentence.
- If a refactor exposes a bug, stop, report it, and don't silently change
  behavior.
- Verify with the repo's own tooling - find the commands in `pyproject.toml`,
  `package.json`, `Makefile`, CI workflows, or README.

Help me write `[what the regex must match]` in `[language or stack]`. Treat a
regex as risky code, not a magic one-liner: it needs a stated purpose, tests
against real inputs, and evidence that it cannot hang on bad input. Write it
only after we agree on the behavior it must have.

## Steps

1. **State the purpose in plain words** - One sentence: what strings must
   match, what must not, and where the pattern runs (validation, extraction,
   a hot path, user-supplied input or not). If the plain statement is hard to
   write, the regex is the wrong tool; say so and propose ordinary string
   handling instead.
2. **Choose the simplest expression** - Prefer the smallest pattern that meets
   the purpose. A string method, an index operation, or a tiny state machine
   often beats a regex entirely. If the language offers a parser for the
   format being matched (JSON, URL, email, numbers), use it instead of a regex.
3. **Write it with anchors and boundaries** - Anchor start and end or use word
   boundaries where the behavior demands it. Match what the caller needs, not
   a fuzzy subproblem, and avoid dot-all or unconstrained groups unless the
   purpose requires them.
4. **Build a corpus and test** - List the inputs that must match, must not
   match, edge cases (empty, whitespace, unicode, mixed case, very long
   strings, lookalike characters, embedded newlines), and run the pattern over
   all of them in a throwaway test. Paste the results; do not assert them.
5. **Hunt for catastrophic backtracking** - Inspect for nested quantifiers and
   alternatives that re-scan the same text (`(a+)+`, `(a|a)*`), especially on
   untrusted input. Check that the pattern either cannot backtrack
   quadratically or that input length is bounded first. If in doubt, time the
   worst-case input you found in step 4 and show it returns quickly.
6. **Make it maintainable** - Add a short comment in a place the team will see
   it: the purpose in plain words, the matching corpus, and why this
   construction. Keep flags and escaping explicit so the next reader can
   predict the behavior.
7. **Land it as a test, not a script** - The adopted pattern ships with its
   corpus as a repeatable test (unit test or checked-in script) that fails if
   the regex behavior changes. A regex without its test cases is a bug waiting
   for an anecdote.

## Rules

- Never write a regex without running it against the agreed corpus and showing
  the output.
- Never accept a pattern with nested loops over the same input on
  user-controlled data without bounding it first.
- Prefer parser, string, or index operations over a regex when the format is
  structured. Regexes are for matching text with a shape; parsers are for
  formats with grammar.
- No pattern change in production code without the corpus test landing in the
  same change.

## Verification

Paste the test run over the corpus (passes and intended non-matches), the
worst-case timing for any adversarial input you constructed, and the final
pattern. Confirm the behavior is pinned by a repeatable test in the repo.

Build `[the agent's job in one sentence]` as an LLM agent: a loop that plans,
calls tools, observes results, and decides the next step until the task is
done or it is safe to stop. Deliver a harness with named tool contracts,
guardrails, an eval set, and a cost/latency budget - and prove each one
works.

## Define the scope first

1. **What the agent does** - The exact task and its boundaries: what the
   agent must decide, what it may never do, and when it is allowed to stop.
   Write the success and failure case in one line each.
2. **Who operates it and how** - Human-in-the-loop, autonomous inside a
   sandbox, or batch job? State which, because it changes the guardrails.
3. **What is out of scope** - Anything the agent must not attempt, and
   anything this pass will not build (logging, billing, UI).

## What to produce

1. **Tool contracts** - Every tool the agent may call, with its input/output
   schema and failure behavior. No tool without a schema; no schema without a
   test fixture. Cite the files that implement each tool.
2. **Context strategy** - What goes into the model context, what stays out,
   how history is trimmed, and how long a session can run. Explain the
   memory-vs-cost trade-off you chose.
3. **The agent loop** - The concrete cycle (plan -> act -> observe -> decide)
   with exit conditions: success, max steps, error budget, safety stop.
   State how a stuck or repeating loop is interrupted or recovered.
4. **Guardrails** - Hard limits on destructive actions, secret handling,
   external calls, and confirmation requirements. Each guardrail must map to
   a real enforcement point in code, cited. Every tool call and its result
   is written to an audit log, stored out of band, so behavior can be
   replayed and reviewed.
5. **Eval set** - At least ten golden tasks covering success cases, edge
   cases, and expected failures, each with a scored rubric (correct output,
   tool misuse, wasted steps, refusing when it should refuse).
6. **Budget and limits** - Measured numbers for cost per run, tokens, and
   latency p50/p95, with a stated target and a rule for when to stop
   spending.

## Method

1. **Read the existing AI code** - Find the project's current LLM usage
   (prompts, clients, evals, RAG). Build on it rather than inventing a
   parallel stack.
2. **Design contracts before code** - Write the tool schemas and eval rubrics
   first; implement against them.
3. **Build the loop thin** - Prefer a small core loop with strict tool
   interfaces over one mega-function. Compose, don't entangle.
4. **Protect before optimizing** - Guardrails and failure handling land
   before prompting tricks or caching.
5. **Run the evals and record** - Execute the golden set, capture pass/fail,
   steps used, tokens, and cost, and write the numbers into the deliverable.

## Verification

- [ ] Every tool has a schema, a fixture, and a cited implementation.
- [ ] Guardrails are exercised by evals that try to violate them, and the
      agent stops or refuses as specified.
- [ ] At least one long-running and one failure-prone scenario is in the eval
      set, with a scored result.
- [ ] Cost and latency are measured on a real run, not estimated.
- [ ] A safety stop fires when max steps or the error budget is hit, proven
      by a recorded run.
- [ ] The audit log captures every tool call and result for a full run, in
      order, and is stored outside the model's context.

## Rules

- No claim about agent behavior without an eval result to back it.
- Never let the agent call a tool that is not in the contract.
- Never spend more than the stated budget; when the budget is hit, stop and
  report.
- If a task cannot be made safely autonomous, say so and propose the
  human-in-the-loop change instead of shipping an unsafe loop.

Load and clean the spreadsheet/CSV data described in this task. Messy exports
are where most data projects actually start; the goal is a validated dataset
plus a report of everything that had to be fixed or rejected, not a script
that just runs without erroring.

## Steps

1. **Detect encoding before parsing** - Don't assume UTF-8. Sniff the byte
   order mark (Excel loves UTF-16 with a BOM on Windows exports) and fall
   back through common encodings (UTF-8, UTF-8-SIG, Windows-1252, UTF-16)
   rather than guessing once and hoping.
2. **Infer types, but make overrides explicit** - Auto-detect column types
   (int, float, date, bool, string) from a sample, then let the caller
   override any column by name. Never silently coerce a column that fails
   inference on some rows; flag it instead of picking a lossy fallback type.
3. **State deduplication and fuzzy-matching rules up front** - Decide and
   document the dedup key(s), whether matching is exact or fuzzy (and the
   similarity threshold if fuzzy), and which duplicate is kept when rows
   conflict. Don't dedupe silently with an undocumented rule.
4. **Validate every row, don't just parse it** - Enforce required columns,
   type ranges, and referential rules (e.g. foreign key exists in a lookup).
   Route failing rows to a quarantine set with a reason per row; never drop a
   row without recording why.
5. **Produce a validation report** - Row counts in, accepted, quarantined,
   and deduplicated, plus a breakdown of quarantine reasons. This is the
   artifact a human actually checks; a clean exit code alone proves nothing.
6. **Round-trip test before trusting the pipeline** - Write the cleaned data
   back out and re-read it; confirm values, types, and row count survive the
   round trip unchanged (watch especially for date/timezone drift, leading
   zeros in ID-like strings, and float precision).

## Rules

- Silent data loss is the cardinal sin: every dropped, coerced, or
  deduplicated row must be counted and explained in the report.
- Never assume the input encoding or delimiter; detect both, and fail loudly
  (not with a mis-parsed but "successful" load) when detection is ambiguous.
- If a column's real-world meaning makes an inference rule unsafe (e.g.
  leading-zero IDs read as integers), say so explicitly rather than silently
  "fixing" it.

Build the requested data pipeline (extract, transform, load) in this
repository. Pipelines fail quietly; yours must fail loudly, resume cleanly,
and make correctness checkable at every stage.

## Steps

1. **Define contracts first** - Source schema(s), destination schema, and the
   transformation rules between them. Write them down (types, nullability,
   ranges) before writing code.
2. **Extract defensively** - Handle pagination, retries, and rate limits on
   APIs; stream large sources instead of loading whole datasets; record what
   was read (counts, watermarks/cursors).
3. **Validate input** - Check row counts against expectations, enforce the
   schema on arrival, quarantine bad records with reasons instead of crashing
   or silently dropping them. Report quarantined volume.
4. **Transform deterministically** - Pure functions where possible; no hidden
   state; unit-test tricky transformations with edge cases (nulls,
   duplicates, timezone boundaries, empty inputs).
5. **Load idempotently** - Running the pipeline twice must not duplicate or
   corrupt data (upserts, staging tables plus swap, or transactional loads).
6. **Make it observable and restartable** - Log per-stage counts and
   duration, emit a success/failure signal, and support resuming from the
   last successful stage rather than a full redo.
7. **Verify end-to-end** - Run on a sample dataset and assert output matches
   hand-computed expectations; then run the rerun test (same input twice
   produces identical output).

## Rules

- Silent data loss is the cardinal sin: every dropped or quarantined row must
  be counted and reported.
- Hardcode nothing that varies per environment (paths, credentials, URLs).
- If source data quality makes guarantees impossible, say exactly what you
  can and cannot promise.

Evaluate the LLM-powered feature in this repository (or a proposed prompt or
model change). Goal: replace "looks fine to me" with repeatable measurements.

## Steps

1. **Define what "good" means** - With the feature owner, pick 3-5 measurable
   criteria (correct extraction vs source, valid JSON schema adherence,
   refusal when information is missing, tone/length bounds). Binary or
   rubric-scored, not vibes.
2. **Build the test set** - 30+ representative cases including adversarial
   ones: empty/noisy input, injection attempts, ambiguous requests,
   multilingual input if supported, and known past failures. Store as
   versioned fixtures.
3. **Automate scoring** - Deterministic checks in code (schema validation,
   exact-match fields, citation presence); model-graded rubrics only where
   necessary, with the rubric shown in the output for auditability.
4. **Run baseline and variants** - Score the current prompt/model, then each
   candidate change. Same test set, same settings, multiple runs where
   outputs are stochastic - report mean and worst case.
5. **Analyze failures, not averages** - Cluster failing cases by cause (prompt
   ambiguity, missing context, model limitation). Fix causes in prompt,
   retrieval, or code; note which failures are inherent and need product
   guardrails instead.
6. **Report honestly** - Table of variants by criteria with pass rates, a
   regression list, cost/latency deltas, and a recommendation with tradeoffs
   named.

## Rules

- Decide pass thresholds before running; changing them after seeing results
  is forbidden.
- Never evaluate on the same examples you tuned prompts against - keep a
  held-out split.
- Log model/version/prompt hash with every run so results are reproducible.

Build the requested retrieval-augmented generation (RAG) feature. The bar:
answers must be grounded in retrieved sources with citations, and quality
must be evaluated against a test set, not vibes.

## Steps

1. **Scope the corpus** - What documents, formats, languages, update
   frequency, size? Confirm you can parse them reliably (encoding, layout,
   tables) before designing anything downstream.
2. **Chunk deliberately** - Chunk by document structure (headings,
   paragraphs) rather than blind character splits; preserve titles and
   section paths as metadata; overlap only if evaluation shows it helps.
3. **Index with metadata** - Embeddings plus the metadata needed for
   filtering (source, date, permissions). Pick the simplest store that meets
   scale - do not reach for a dedicated vector database before a plain
   Postgres/pgvector-style setup proves insufficient.
4. **Retrieve well** - Start with hybrid retrieval (keyword + vector) if the
   corpus has proper nouns or IDs; rank and cap the context; apply permission
   filters at query time, not just ingest time.
5. **Generate with grounding rules** - The prompt must require: answer only
   from provided context, cite sources inline, say "I don't know" when
   context is insufficient. Never let the model silently fill gaps from its
   own memory.
6. **Evaluate before shipping** - Build a golden set of question/expected-
   source pairs (20+ to start). Measure retrieval hit rate and answer
   faithfulness; iterate chunking and retrieval against these numbers.
7. **Harden operations** - Track cost and latency per query, cache frequent
   retrievals, plan re-indexing for corpus updates, and log queries with
   citations for debugging.

## Rules

- No shipping without eval numbers on the golden set; report them.
- Permission checks happen at retrieval time - filtered search alone is not
  authorization.
- Every answer must trace to cited chunks; uncited claims are defects.

Build the requested web scraper/crawler. Scraping without guardrails gets
IPs banned, breaks on the next redesign, and can create legal exposure;
build it defensively from the start.

## Steps

1. **Respect robots.txt and ToS before writing a single request** - Fetch and
   parse `robots.txt`, honor disallowed paths and crawl-delay directives, and
   check the site's terms of service for an explicit scraping policy. If the
   ToS forbids scraping, say so and stop rather than proceeding anyway.
2. **Identify honestly** - Set a descriptive User-Agent string with contact
   info (e.g. `myproject-bot/1.0 (+https://example.com/contact)`), not a
   spoofed browser UA. If the site offers an API, use it instead of scraping
   HTML.
3. **Rate-limit and back off** - Enforce a minimum delay between requests to
   the same host (respect `Crawl-delay` if present), add jitter, and
   exponentially back off on 429/503 responses instead of retrying
   immediately.
4. **Write selectors resilient to markup drift** - Prefer stable attributes
   (`data-*`, `id`, semantic tags) over deep positional CSS paths that break
   on the next redesign. Add a fallback selector chain and log when the
   primary selector misses so drift is caught early, not silently.
5. **Make crawls incremental and resumable** - Checkpoint progress (last
   page/ID processed) so a crash or interruption resumes instead of
   restarting from zero. Deduplicate against already-fetched items on
   resume.
6. **Track politeness and error budgets** - Log requests/sec against the
   configured limit, error rate by status code, and stop (don't keep
   hammering) once an error budget is exceeded - that's a signal the site
   changed or is blocking you, not a transient blip to retry through.

## Rules

- Never bypass a CAPTCHA, paywall, or authentication wall to scrape content
  behind it.
- Never scrape personal data beyond what's already public and permitted by
  the site's policy; don't aggregate PII across sources without a stated
  lawful basis.
- If `robots.txt` or ToS is ambiguous or unreachable, treat that as "ask a
  human before proceeding," not as permission by default.

Optimize the specified slow SQL query or query set. Work like a DBA: measure,
read the plan, change one thing, measure again. No index is added without
evidence it will be used.

## Steps

1. **Baseline** - Capture current runtime on realistic data volumes (not dev
   toy data) and save `EXPLAIN ANALYZE` (or equivalent) output. Note rows in
   and out, and where time goes (seq scan, sort, spill to disk).
2. **Diagnose** - From the plan, identify the dominant cost: missing index,
   non-sargable predicates (functions on indexed columns), N+1 patterns in
   app code, over-fetching columns/rows, bad join order, stale statistics.
3. **Fix one thing at a time** - Candidate moves: covering/partial/composite
   index matched to the actual predicate and sort; rewriting the query
   (sargable predicates, `EXISTS` instead of `COUNT` joins, window functions
   instead of self-joins); batching app-side round trips; denormalizing a hot
   aggregate. After each change, re-run EXPLAIN and compare.
4. **Count the costs** - Every index slows writes and consumes space: list
   the affected write paths and judge whether the trade is worth it. Drop or
   reject indexes the planner won't use.
5. **Guard the win** - Add a regression test or benchmark that fails if the
   query regresses past a threshold; write the migration for the index/change
   with a rollback path and note lock implications on big tables
   (`CONCURRENTLY` or equivalent).

## Output

Before/after plans and timings, the changes as migrations, and a plain-
language explanation of why the plan changed.

## Rules

- Never report "should be faster" - show measured before/after on realistic
  data.
- One hypothesis per iteration; if a change doesn't move the plan, revert it.
- Verify the result set is identical before and after - correctness first.

Set up backups and disaster recovery for this system. The deliverable is not
backup jobs - it is demonstrated restores, documented recovery steps, and
known RTO/RPO numbers.

## Steps

1. **Classify the data** - Inventory data stores and ask per store: how much
   data loss is tolerable (sets RPO) and how long may recovery take (sets
   RTO)? Backing up everything identically is rarely the answer; tier by
   criticality.
2. **Design the backup scheme** - Right tool per store (managed snapshots,
   dump/restore, replication with point-in-time recovery); 3-2-1 rule (three
   copies, two media, one offsite or off-account); encryption at rest;
   retention policy with legal considerations noted. Access-control the
   backups too - they contain everything.
3. **Automate and monitor** - Scheduled jobs with failure alerting (a backup
   job that fails silently is worse than none - it lies), success/failure
   recorded, and restore tooling versioned alongside the app so it never
   drifts out of compatibility.
4. **Prove restores work** - Restore into a scratch environment from the real
   backups: a full restore, plus point-in-time if supported. Time it. Verify
   integrity (row counts, spot-checked records, app smoke tests against
   restored data). Document the exact commands that worked.
5. **Write the DR runbook** - Scenario-driven: "database region lost", "bad
   migration shipped", "account compromised". Per scenario: detection, decision
   tree, recovery steps referencing the tested commands, and communication
   owner.
6. **Schedule drills** - Restore tests on a calendar (quarterly is common),
   re-run after major schema/architecture changes, and update RTO/RPO numbers
   from measured results rather than hopes.

## Output

Backup configuration as code, a restore runbook with verified commands, and a
table of stores with their measured RPO/RTO.

## Rules

- A backup that has never been restored is a hypothesis, not a capability -
  prove at least one restore before calling this done.
- Alerting on backup failure is mandatory; silent failures don't count.
- Never test restores against production data in place; use scratch
  environments.

Design/update the database schema for `[feature/change]` in this repository
and write the migrations. Treat the schema like a public API: changes must be
backward-compatible unless the migration plan explicitly says otherwise.

## Steps

1. **Understand the data** - Read the existing schema, models, and the code
   that reads/writes this data. Understand current constraints, indexes, and
   how queries are actually made. Don't design in a vacuum.
2. **Design the change** - Keep it minimal and consistent with existing
   naming and conventions. Consider: types, nullability, defaults, indexes for
   the real query patterns, constraints, and referential integrity.
3. **Write backward-compatible migrations** - Apply the migration framework
   the repo already uses (check for Alembic, Prisma, Django, Knex, Flyway,
   etc.). Default rule: old code must keep working against the new schema.
   Follow this pattern:
   - **Expand**: add new columns/tables without breaking existing reads and
     writes; make new columns nullable or defaulted first.
   - **Migrate data**: backfill new columns in a separate step where needed,
     in a transaction.
   - **Contract**: only then drop old columns/tables (often in a later
     migration after the old code is gone).
   - Down migration must safely reverse the up migration (drop what you
     added, restore what you removed).
4. **Watch for the classic failures** - Adding `NOT NULL` to a populated
   table, renaming columns (use add + migrate + drop instead), changing a
   column type that breaks comparisons, adding an index that locks a big
   table. Flag any that apply.
5. **Verify** - Run the migration up and down against a local database, run
   the test suite, and confirm the new code paths work against the migrated
   schema. Confirm existing tests still pass on the new schema.

## Rules

- Never write a migration that drops or renames data without a stated,
  approved plan.
- Never run destructive migrations against a real database without explicit
  confirmation.
- Keep each migration focused on one logical change.
- If the schema change can't be made backward-compatible, stop and flag the
  coordination needed instead of hiding it.

Prepare a safe deployment of `[version / branch]` of this application to
`[environment]`. A deployment is a risky operation: the plan must be precise,
verifiable, and reversible.

## What to produce

1. **Preflight checklist** - Everything that must be true before deploying:
   CI/tests green, migrations reviewed, env/config changes known, secrets in
   place, dependencies (DB, cache, external APIs) healthy, backups taken if
   the deployment mutates data.
2. **The deploy steps** - Exact, ordered commands (or the platform's steps):
   build/package, run migrations (before or after rollout - state which and
   why), update instances, verify. Include how config/secrets are supplied.
3. **Verification after deploy** - How to confirm the deployment actually
   works: health checks, smoke tests, logs to watch, key user flows to
   exercise. Include the specific checks, not "verify it works".
4. **Rollback plan** - The exact steps to revert to the previous version, and
   how to handle the tricky cases (schema migration already applied,
   half-rolled-out state, cache warm-up). State the trigger conditions for
   rolling back.
5. **Risk notes** - Known risks of this specific release (breaking changes,
   perf-sensitive features, data-affecting code) and how to watch for them.

## Method

- Read the repo's existing deploy scripts, CI/CD config, README, and any
  runbooks. Build on what exists; don't invent a parallel process.
- Verify commands where you can (check scripts, run read-only/`--dry-run`
  variants, confirm config paths and env var names exist). Don't fabricate
  commands you haven't validated.
- Match the environment's conventions (naming, logging, alerting).

## Rules

- Never run a real deployment without user confirmation, and never deploy to
  production from an unreviewed/unverified plan.
- Never put secrets in the runbook; reference how they're supplied.
- If something in the plan is uncertain, mark it as needing confirmation -
  don't paper over it.

Create a Docker image for this application. The goal: a reproducible, small,
secure image that runs the app the way it's meant to run.

## Requirements

1. **Understand the app first** - Read how the app is built and run: language,
   runtime, build steps, entrypoint, required env vars, ports, and config.
   Read the README, manifests, and the actual code - don't guess the stack.
2. **Write a real Dockerfile** - Use multi-stage builds where the stack
   benefits (build stage for compiling/dependency-install, slim runtime stage
   without build tools and source). Prefer the official base images and pin
   versions. Cache-friendly ordering: dependency layers before source.
3. **Run as a non-root user** - Create and switch to an unprivileged user in
   the image unless the app genuinely needs root.
4. **Don't ship junk** - Add a `.dockerignore` (node_modules, .git, tests,
   build caches, secrets, `.env`). Never copy secrets or `.env` files into the
   image. Keep the image as small as reasonable - document any files you
   deliberately must include.
5. **Make it reproducible & runnable** - Set sensible `EXPOSE`, `ENV`,
   `WORKDIR`, `CMD`/`ENTRYPOINT`. Ensure healthcheck/readiness is possible
   where the app supports it. Container runs with required env vars provided
   externally (config, not baked in).
6. **Verify** - `docker build` it without warnings that matter, run it locally
   with the documented env, and confirm the app starts and responds. Check the
   image with a security scanner if available (e.g. `docker scout`,
   `trivy`). Fix anything real it flags.
7. **Document** - Update/extend the README with build and run instructions
   (`docker build`, `docker run`, required env vars, ports) if not already
   present.

## Rules

- Never use `latest` tags for base images in a Dockerfile meant for
  production/reproducible builds.
- Never install package managers or compilers in the runtime stage just for
  convenience.
- Never commit secrets, private keys, or `.env` files to the image or the repo.
- If the app is hard to containerize cleanly (stateful, needs host services),
  stop and flag it rather than hacking around it.

Ship the requested feature behind a feature flag with a progressive rollout
plan. Flags exist to decouple deploy from release: the code ships dark,
enables gradually, and can be killed in seconds without a redeploy.

## Steps

1. **Decide the flag's shape** - Boolean, percentage, or per-segment? Who
   does it target (internal users, beta cohort, percent of traffic)? Where
   does flag state live (platform SDK, DB-backed, config service)? Prefer the
   repo's existing flag system if one exists.
2. **Wrap at the right granularity** - Flag the capability, not every line:
   one decision point at the entry to the new path, both branches complete
   and shippable. The old path stays intact and tested until cutover.
3. **Keep both paths healthy** - Tests cover flag-on AND flag-off; typecheck
   doesn't rot the dormant branch; telemetry identifies which variant served
   each request.
4. **Plan the rollout ladder** - Internal, then 1%, 10%, 50%, 100% - with
   explicit go/no-go metrics at each step (error rate, latency, conversion,
   support tickets) and a named owner. Define kill criteria before enabling
   anything.
5. **Instrument the switch** - Enabling/disabling must not require a deploy,
   must take effect within seconds, and must be audited (who flipped what,
   when). Test the kill switch by flipping it off mid-experiment.
6. **Clean up on a schedule** - Once stable, remove the flag and the dead
   branch within an agreed window; stale flags compound into unreadable code.
   Record the removal task immediately, not "later".

## Rules

- No flag without a documented kill criterion and owner.
- Flag-on and flag-off must both pass CI - a broken dormant branch is a live
  grenade.
- Schema changes behind flags must stay backward-compatible with both states,
  since rollback can leave mixed data.

Help me debug this incident or write a post-mortem for `[incident description
/ error / symptom]`. The goal: understand what happened, fix it, prevent it
from happening again, and document it honestly.

## For live debugging

1. **Triage** - Establish the current state: What's broken? When did it start?
   What changed recently (deploys, config changes, traffic spikes)? Is it
   affecting all users or a subset? Gather the evidence: error logs, metrics
   dashboards, recent deployments, and alerts that fired.
2. **Contain** - What can be done right now to reduce impact? Roll back the
   last deploy, scale up, disable the broken feature, route traffic away.
   Do this first, then investigate root cause.
3. **Investigate** - Trace the failure from the symptom to the root cause:
   read the error stack trace, follow the code path, check the database
   state, verify external service responses. Use the repo's debugging tools
   and logs. Do not guess - gather evidence.
4. **Fix** - Apply the minimal fix that addresses the root cause. Verify the
   fix works by monitoring the metrics and logs after deployment. Do not
   layer fixes on top of fixes.
5. **Verify recovery** - Confirm the service is healthy: error rates dropped,
   latency normalized, and affected functionality works. Check for secondary
   issues (cascading failures, data inconsistencies).

## For post-mortem writing

1. **Timeline** - Reconstruct the timeline from alerts, deploys, and logs.
   What happened, when, and in what order.
2. **Root cause** - What was the underlying technical cause? Be specific:
   code-level detail, not "a bug was introduced."
3. **Impact** - Quantify: users affected, duration, data loss (if any),
   revenue impact (if applicable).
4. **What went well** - What detection, response, or mitigation worked?
   Preserve these.
5. **What went wrong** - What failed in the system or the process? Be
   specific and factual.
6. **Action items** - Concrete, assigned, with deadlines: code fixes,
   process changes, monitoring additions. Each action must prevent a
   specific aspect of this incident from recurring.

## Rules

- Never assign blame to individuals - focus on systemic causes and
  process improvements.
- Never write "add more tests" as an action item without specifying what
  tests and what they would catch.
- Never skip the containment step during a live incident to investigate
  root cause - reduce impact first.
- If the root cause is uncertain, say so and list what evidence supports
  each hypothesis.

Set up / modify the infrastructure for this repository using
`[Terraform/OpenTofu/CloudFormation/CDK/Pulumi]`. Treat infrastructure as
code: reviewable, versioned, and safely applied.

## Requirements

1. **Read the existing setup** - Find existing IaC, cloud configs, CI/CD
   references, and README instructions. Reuse and extend what exists; don't
   reinvent the layout. Match the repo's provider/module conventions.
2. **Design with intent** - Define only what the app actually needs:
   compute, storage, networking, IAM, DNS/security groups. Name resources
   consistently, tag them, and use variables for anything environment-specific.
   Keep modules small and reuse the provider's built-in modules over
   reinventing them.
3. **Least privilege** - Grant IAM roles/permissions as narrow as the app
   needs. No wildcard `*` actions or over-broad network rules without a reason
   stated in a comment. No secrets in the IaC code - use secrets manager/vars.
4. **State safety** - Remote state with locking (e.g. S3 + DynamoDB backend),
   never commit state files or `.tfstate` to the repo. State in the README
   how state is managed.
5. **Plan before apply** - Run `plan` and review the diff before any apply.
   Never `apply` with `-auto-approve` unless the user explicitly confirms, and
   never apply a plan that creates/destroys resources you didn't intend.
6. **Verify** - Validate the config (`terraform validate`, `cdk synth`,
   etc.). If possible, run a plan against the real environment and confirm it
   matches intent. Flag anything destructive.
7. **Document** - README gets a short "infrastructure" section: what exists,
   how to plan/apply, and where state lives.

## Rules

- Never destroy or resize resources without explicit user confirmation.
- Never hardcode secrets; never commit credentials or private keys.
- If the cloud setup can't be validated without real credentials, say so and
  produce the config plus a clear plan-verification step for the user.

Deploy this application to Kubernetes properly. The bar: pods pass real
health checks, rollouts don't drop requests, nothing runs as root, and
resource usage is bounded and visible.

## Steps

1. **Confirm the image is deployable** - Small, non-root, no floating
   `latest` tag, configuration via env/files rather than rebuilds. If the
   Dockerfile needs fixing, fix it first.
2. **Write manifests the declarative way** - Deployments (not bare pods),
   ConfigMaps/Secrets for config, Services, Ingress or HTTPRoute. Prefer
   Kustomize overlays per environment over copy-pasted YAML. Resource
   requests should match observed usage; limits prevent noisy neighbors.
3. **Health probes that mean something** - Liveness = process healthy (cheap,
   never depends on other services); readiness = able to serve (checks what
   actually matters); startupProbe for slow boots. A probe hitting `/` of a
   SPA is not a health check.
4. **Zero-downtime rollout** - Tune maxUnavailable/maxSurge; handle SIGTERM
   (or a preStop delay) so connections drain; set
   terminationGracePeriodSeconds long enough for in-flight work; gate on
   readiness during startup. Verify by watching error rates during a rollout.
5. **Lock down and observe** - securityContext (non-root, read-only rootfs,
   dropped capabilities), NetworkPolicies where the cluster enforces them,
   secrets from a secret manager rather than committed YAML, autoscaling
   based on real metrics, PodDisruptionBudget for availability tiers.
6. **Verify end-to-end** - Apply to a staging namespace, run smoke tests
   against the service, kill a pod under traffic and show zero failed
   requests, then tear down cleanly.

## Rules

- No `latest` tags and no root containers.
- Every manifest change must be applied and verified - YAML that was never
  applied is fiction.
- If the cluster lacks a feature (e.g., NetworkPolicy enforcement), say so
  rather than pretending the YAML protects anything.

Set up monitoring and observability for `[service / application / endpoint]`.
The goal: when something goes wrong, you know what, where, and why within
minutes, not hours of log-diving.

## Steps

1. **Understand the system** - Read the code to identify the critical paths,
   external dependencies, error conditions, and performance-sensitive
   operations. Understand what "healthy" looks like before defining what
   "broken" looks like.
2. **Structured logging** - Add structured (JSON) logging at key points:
   request entry/exit, external service calls, database queries, error
   paths, and business-critical operations. Use consistent log levels
   (error, warn, info, debug) and include correlation IDs for request
   tracing. Follow the repo's existing logging conventions.
3. **Define metrics** - Instrument the four golden signals:
   - **Latency** - response time for requests (p50, p95, p99)
   - **Traffic** - requests per second
   - **Errors** - error rate and error types
   - **Saturation** - CPU, memory, connection pool usage
     Use the repo's existing metrics library (Prometheus client, StatsD,
     OpenTelemetry).
4. **Set up dashboards** - Create dashboards that answer the questions you'd
   ask during an incident: Is the service healthy? What's the error rate?
   Which endpoints are slow? Are dependencies responding? Keep dashboards
   focused - one service per dashboard, key signals visible at a glance.
5. **Configure alerts** - Create alerts for actionable conditions only:
   error rate above threshold, latency exceeding SLA, dependency
   unreachable, disk/memory critical. Every alert must have a clear
   severity, a runbook link, and a person/team who owns the response.
   Avoid alert fatigue from noisy or informational alerts.
6. **Verify** - Trigger a real error or simulate one (kill a dependency,
   return an error). Confirm the logs capture it, the metrics reflect it,
   the dashboard shows it, and the alert fires.

## Rules

- Never add logging in hot loops or high-frequency paths without considering
  the performance impact.
- Never create alerts that nobody should act on - if you can't define the
  response action, don't alert on it.
- Never use plain text logging when structured logging is available in the
  stack.
- If the repo already has observability tooling, extend it rather than
  introducing a parallel system.

Generate API documentation for `[endpoint / route group / service]` in this
repository. The goal: docs that accurately describe the real API, not an
idealized version that doesn't match the code.

## Steps

1. **Read the actual code** - Trace each endpoint from route definition through
   handler logic to response. Identify the request shape (params, body,
   headers, query), the response shape (status codes, body schema, headers),
   and error cases. Do not infer from route names alone.
2. **Identify the output format** - Check what the repo already uses: OpenAPI
   YAML/JSON, Markdown endpoint docs, JSDoc/OpenAPI annotations, or none.
   Follow the existing format. If none exists, propose OpenAPI 3.x as the
   standard.
3. **Document each endpoint** - For every endpoint, capture: HTTP method and
   path, description, all parameters (path, query, header, body) with types
   and constraints, success response (status code + schema), error responses
   (status codes + when they occur), authentication requirements, and rate
   limits if applicable.
4. **Add examples** - Include realistic request and response examples for each
   endpoint. Use actual data shapes from the code, not placeholder values.
   Show both success and error examples.
5. **Verify accuracy** - Cross-check every documented parameter, response
   field, and status code against the actual code. Run the endpoint (or read
   the tests) to confirm the documented behavior matches reality.
6. **Integrate** - If the repo uses an API documentation site, ensure the new
   docs render correctly. If generating an OpenAPI spec, validate it with a
   spec validator.

## Rules

- Never document endpoints that don't exist in the code.
- Never document parameters or response fields that the code doesn't actually
  use or return.
- If the code handles an edge case (e.g. a specific error code), document it -
  don't omit it because it's uncommon.
- If the existing docs and the code disagree, the code wins and the docs
  need fixing.

Write/update documentation for this repository: `[README / API docs / setup
guide / CONTRIBUTING]`. Good docs are accurate, honest, and easy to skim.
Never write docs that sound confident but say nothing.

## Requirements

1. **Verify first** - Run the actual commands you document (install, build,
   run, test) or read the code, before claiming they work. A doc that says
   `npm install && npm start` must be a path you've confirmed. Check existing
   docs for stale instructions and correct them.
2. **Write for the reader** - The reader is a newcomer with your exact task:
   what they need to know to succeed, in order. Lead with the one-sentence
   value. Then quickstart, then details. No walls of text - use short
   sections, lists, and code blocks.
3. **Show real examples** - Use concrete examples that match the code's actual
   behavior. Copy real output where it helps. Don't invent flags, options, or
   edge behaviors that don't exist.
4. **Match the project's voice and style** - Imitate the tone, heading style,
   and formatting conventions already in the repo's docs. Keep it consistent
   with the existing README/CHANGELOG/CONTRIBUTING.
5. **Keep it current** - If you're editing existing docs, remove what's now
   wrong, don't just append. Check that code samples, links, and version
   references still hold.
6. **Cover the real friction points** - Include troubleshooting only for
   genuinely common issues, from real experience (or clearly-known ones), not
   invented FAQ filler.

## Rules

- Never document features that don't exist, and never omit setup steps that
  are required.
- Don't copy-paste marketing fluff or generic boilerplate - say what THIS
  project does.
- If the code and the docs disagree, trust the code and fix the docs.

Add or improve inline documentation (JSDoc, docstrings, comments) for
`[file / module / function]` in this repository. The goal: documentation that
helps a future developer understand the non-obvious decisions, not noise that
restates what the code already says.

## Steps

1. **Read the code first** - Understand what each function, class, and module
   actually does. Trace the logic, identify edge cases, and note any
   non-obvious behavior. Do not write docs from the function signature alone.
2. **Follow the repo's conventions** - Check the existing docstring/JSDoc style
   in the codebase: format (JSDoc, reST, Google, NumPy), level of detail,
   where they are used, and where they are omitted. Match the existing
   conventions exactly.
3. **Document what matters** - Add documentation to:
   - Public functions and classes that other developers will use
   - Non-obvious parameters (what are the valid values, what's the default
     behavior)
   - Return values that are not self-explanatory
   - Side effects, mutations, or state changes
   - Error conditions and when they are thrown
   - Comments explaining "why" when the code does something surprising
4. **Skip what's obvious** - Do not document: getters/setters that do exactly
   what their name says, trivial one-line functions, private helpers with
   clear names, or parameters whose types make their purpose obvious.
5. **Keep it concise** - One to three lines for most functions. A paragraph
   max for complex classes. Every sentence must add information the code
   doesn't already convey.
6. **Verify accuracy** - Read the docs you wrote against the actual code. If
   the docs describe behavior that doesn't match the implementation, fix the
   docs.

## Rules

- Never write docstrings that restate the function name or parameter names
  ("this function takes a name and returns a greeting").
- Never add documentation just to hit a coverage target - quality over
  quantity.
- Never use TODO comments in documentation - either write the doc or remove
  the placeholder.
- If the code is too complex to document concisely, the code may need
  refactoring rather than longer docs.

Build a README.md for this repository from scratch (or rewrite the existing
one). The goal: a README that helps a newcomer understand what this project
does, why they'd use it, and how to get started in under 2 minutes.

## Steps

1. **Understand the project** - Read the code, existing docs, package
   manifests, and any config to understand: what it does, who it's for, what
   problem it solves, and how it's different from alternatives. Do not guess
   from the project name alone.
2. **Structure the README** - Use this order (adapt based on project needs):
   - One-sentence description of what it is
   - 2-3 sentence value proposition (why use this)
   - Quick start (install + minimal usage in under 5 commands)
   - Features or capabilities (what it can do)
   - Configuration (env vars, config files, CLI flags)
   - Development setup (contributing, running locally)
   - License
3. **Write honest copy** - Describe what the project actually does, not what
   you wish it did. Use the project's own terminology. Avoid marketing fluff,
   superlatives, and buzzwords. If the project has limitations, mention them.
4. **Show real examples** - Include code snippets that actually work. Verify
   every command you document by reading the code or running it. Show real
   output where it helps understanding.
5. **Add badges and links** - Include build status, license, and any other
   relevant badges. Link to CONTRIBUTING.md, LICENSE, and related docs.
6. **Verify everything** - Every command in the README must work. Every link
   must resolve. Every code snippet must be syntactically correct for the
   project's language.

## Rules

- Never write a README that sounds impressive but doesn't answer "what does
  this do and how do I use it?"
- Never include commands you haven't verified work.
- Never add placeholder sections ("TODO: add more docs") - either write the
  section or remove it.
- Keep the README scannable: short paragraphs, code blocks, and lists. No
  walls of text.

Write the release notes/changelog for `[version / tag / range of commits]` of
this repository, based on the actual git history. Read the commits - don't
write from memory or from the release title alone.

## Steps

1. **Gather the commits** - `git log` the range (compare with the previous
   release tag). Read titles and the diffs for anything ambiguous. Use
   conventional-commit prefixes if the repo uses them.
2. **Categorize** - Group changes as: **Added**, **Changed**, **Fixed**,
   **Removed**, **Deprecated**, and **Security** (match the repo's existing
   changelog convention if it has one). Order within each group by importance
   or by tag/date as the repo does.
3. **Summarize user-visible impact** - Each entry should say what changed and
   (where it matters) what the user/developer must know: a breaking change
   must be called out loudly with migration guidance or a link to it.
4. **Be accurate** - Include only what actually landed. Include dependency
   bumps only if they affect users. Never pad with "improved performance"
   unless a commit actually did that.
5. **Follow conventions** - Keep the repo's existing changelog format,
   heading style, and versioning scheme (SemVer if the repo uses it).

## Rules

- Never invent entries or describe commits you haven't read.
- Breaking changes go at the top of their section and are flagged as such.
- If the repo uses auto-generated release notes, improve and reconcile with
  them rather than duplicating or conflicting.
- Verify the version numbers and links you reference exist.

Build a reusable UI component for `[component name and purpose]` in this
repository. The goal: a component that works across multiple contexts, is
accessible, and follows the project's design system conventions.

## Steps

1. **Understand the design system** - Read the existing components, design
   tokens (colors, spacing, typography), and UI patterns in the codebase.
   Understand the conventions: how components are structured, how props are
   typed, how styling is applied (CSS modules, Tailwind, styled-components,
   CSS-in-JS). Follow these exactly.
2. **Define the API** - Design the component's props: what it accepts, what's
   required vs optional, sensible defaults. Keep the API minimal - props
   should be intuitive and not require reading docs to use. Use TypeScript
   types or equivalent for prop validation.
3. **Handle variants and states** - Support the common variants (size, color,
   style) and states (disabled, loading, error, empty). Use composition
   patterns (children, render props, compound components) over boolean prop
   proliferation.
4. **Build it accessible** - Ensure keyboard navigation works, focus is
   visible, ARIA attributes are correct, color meets contrast requirements,
   and screen readers announce state changes. Reference the accessibility
   review checklist in this repo.
5. **Add stories or examples** - Create Storybook stories (or equivalent
   documentation) showing: each variant, each state, edge cases (long text,
   no data, error state), and composition with other components.
6. **Verify** - Test the component manually: keyboard-only navigation,
   screen reader output, responsive behavior. Run the test suite. Check that
   the component renders correctly across the supported browsers.

## Rules

- Never build a component that only works in one specific context - it must
  be reusable.
- Never hardcode values that should come from design tokens (colors, spacing,
  fonts).
- Never skip accessibility - a component that isn't accessible is not done.
- If the codebase already has a similar component, extend it rather than
  building from scratch.

Implement `[the page or component]` to match the provided design
`[reference: link, file, or screenshot path]` in this repository. The goal
is visual parity at the target breakpoints - close enough that a side-by-side
comparison shows only intentional differences.

## Steps

1. **Extract the design tokens first** - Read the design and list its
   spacing, type scale, colors, radii, and shadows as named values. If the
   project has a design token file, map to it; if not, propose values that
   mirror the design exactly rather than approximating them inline.
2. **Note the unsupplied specifications** - Track every measurement the
   reference does not show (exact spacing, hover states, breakpoint
   behavior). List these as assumptions to confirm, and pick defaults
   consistent with the design system.
3. **Build with the existing components** - Use the repo's components and
   styles. Only write new CSS or new components when the design genuinely
   has no existing equivalent.
4. **Match layout at the target breakpoints** - Verify the composition holds
   at the breakpoints the design implies (mobile, tablet, desktop). A design
   drawn desktop-only still needs a defined, intentional mobile state.
5. **Compare, find gaps, fix** - Take a screenshot of the implementation at
   the same size as the reference and diff them side by side. List every
   visible difference (spacing, size, color, alignment), fix the real ones,
   and record which differences remain and why.
6. **Verify behavior and quality** - Confirm keyboard navigation, focus, and
   responsive behavior on the implemented element. Run the repo's tests and
   linters.

## Verification

- [ ] Every spacing, type, and color value in the output is traceable to the
      design or listed as an assumption.
- [ ] A side-by-side comparison was done and the remaining differences are
      named and justified.
- [ ] The component holds at the agreed breakpoints with no overflow or
      collapsed layout.
- [ ] Accessibility basics (keyboard, focus, contrast) pass on the new code.
- [ ] The repo's test suite and linters pass.

## Rules

- Never present invented measurements as coming from the design; tag them as
  assumptions.
- Never rebuild existing components; reuse them.
- Never call it done before the side-by-side comparison step.
- If the reference is ambiguous, list the ambiguity and your default rather
  than silently choosing.

Internationalize this application so adding a new language is a translation
task, not a code task. Extract everything locale-dependent; verify with a
pseudo-locale before writing real translations.

## Steps

1. **Extract user-facing strings** - Move every hardcoded string (UI labels,
   errors, emails, aria-labels, dates in templates) into message catalogs
   with stable keys that describe intent, not wording. No concatenating
   fragments across messages - full sentences per message with interpolation.
2. **Localize formatting, not just text** - Dates, times, numbers, currency,
   and percentages via the platform's Intl/i18n APIs; store timestamps in
   UTC and render local; use locale-aware collation for sorting and search.
3. **Handle plurals properly** - Use ICU plural/select syntax instead of
   adding an "s"; cover all plural forms the target languages need (many
   languages have more than one/other).
4. **Make layout resilient** - German and Finnish run ~35% longer; Thai has
   no spaces: no fixed widths on text containers, wrapping/ellipsis allowed,
   buttons sized by content. Mirror layout for RTL languages (logical CSS
   properties, direction-aware icons and arrows).
5. **Set up the plumbing** - Locale detection/negotiation (URL prefix or
   header/cookie per project convention), explicit locale switching, a
   fallback chain (region to base language to default), and HTML `lang`/`dir`
   attributes kept correct.
6. **Verify with pseudo-localization** - Render in a pseudo-locale (accented,
   ~40% longer text) to flush out truncation, overflow, missed extractions,
   and concatenation bugs. Then add one real translation and run the full
   flows in it.

## Rules

- Zero hardcoded user-facing strings may remain - grep to prove it.
- Never build sentences by concatenating translated fragments.
- Language names, dates, and numbers inside content count as strings:
  extract them too.

Create an Instagram carousel post about this repository, following the repo's
existing visual identity. Deliver it as a single self-contained HTML file
containing `N` slide sections (ask me for `N` if I haven't said, otherwise default
to 8), each sized exactly **1080x1080 pixels**, ready for me to open in a
browser and screenshot in order as an Instagram carousel.

## Step 1 - Understand the content (what I'm posting about)

1. **Read the repo's README.md** and, if present, its `CHANGELOG.md`, category
   folders, and sample files. Extract: what the project does, who it's for, its
   headline value proposition, and 3-5 concrete, real features or use-cases I
   can cite on the slides.
2. **Gather real facts, not invented ones** - count actual entries/items per
   category (e.g. `find . -name '*-prompt.md'`), pull real feature names, real
   numbers, and real sample titles directly from the repo. Every number or claim
   that goes on a slide must be verified against the actual files. Never make up
   stats, counts, or feature names.

## Step 2 - Discover the brand identity (the visual style)

Find and mirror the repo's existing branding rather than inventing a new look:

1. Look for brand artifacts in the repo tree and the owning organization:
   - SVG logos / lockups (e.g. `logo-lockup.svg`, `profile/*.svg`).
   - README badges, shields, and the org profile README - these often leak the
     exact brand hex colors.
   - Any mentions of the website/handle/account (Instagram, Twitter/X, etc.).
2. **Extract the brand tokens:**
   - **Colors** - the 1-3 accent colors actually used in the logo/badges plus a
     neutral background and a text color. Record their exact hex values.
   - **Fonts** - the heading and mono/label font families used in the lockup or
     badges (e.g. a display font for headings and a monospace for labels).
   - **Logo** - rebuild the logo mark as inline SVG (from the official SVG or by
     approximating its shapes/colors) so it can be placed on each slide.
   - **Voice** - pull the org tagline and tone from the README (e.g. "built by
     students, for students") and reuse its phrasing.
3. If I gave you a reference post or a style description, follow it; otherwise
   mirror the extracted brand identity.

## Step 3 - Write the carousel script

Plan `N` slides with a clear narrative arc. Recommended default structure (8
slides, adapt to `N`):

1. **Cover / hook** - a bold, benefit-led headline that makes people swipe. Add
   a small "swipe →" cue.
2. **The problem** - the pain the project solves.
3. **What it is** - project overview: free/open-source status, key facts and
   verified numbers.
4. **Feature / category grid** or a key breakdown (chips with real per-category
   counts).
5. **How it works** - a numbered 2-4 step walkthrough.
6. **Why it's different** - the differentiators / core philosophy as short cards.
7. **Real examples** - a few concrete, real items pulled from the repo in step 1.
8. **CTA** - clear action (e.g. "star on GitHub"), the handle/URL, and a
   "save/share" prompt.

Keep on-screen text short and scannable. Aim for one idea per slide, big
headlines, and no walls of text.

## Step 4 - Build the HTML

1. **One self-contained `.html` file** with all `N` slides as sibling
   `<section class="slide">` elements, each exactly `1080px x 1080px`.
2. **No external dependencies** - no CDN links, no external fonts, no remote
   assets. Use the extracted brand fonts with sensible system fallbacks (e.g.
   `'Space Grotesk', system-ui, sans-serif`). Inline all SVG.
3. **Shared slide chrome** for consistency (the "template"): the logo in the
   top-left, a `NN / NN` page indicator top-right, and a footer strip with the
   handle and a short tagline. Repeat this exact chrome on every slide (vary
   only the content and the CTA).
4. Use CSS custom properties (`:root` variables) for the brand colors so they're
   easy for me to tweak in one place.
5. Use the brand palette, the brand fonts for headings and mono for labels/tags,
   and the brand voice for all copy.

## Step 5 - Verify the layout

Programmatically confirm, for EVERY slide, that the content fits within the
1080x1080 bounds and does not overflow into the footer:

- Render the file (e.g. with a headless browser) and measure each slide's
  content bounding box against the footer boundary.
- Check the slide is exactly 1080x1080 and that `overflow:hidden` on the slide is
  only clipping intentional decorative elements - not real text or cards.
- If any slide overflows, tighten that slide's font size, spacing, or copy and
  re-check until all slides fit cleanly.

If a headless browser isn't available, reason carefully about the layout: keep
content vertically centered, cap headline sizes so the longest allowed text fits,
and leave generous margins.

## Step 6 - Deliverable

In the same HTML file, below the slides, include a clearly-labeled section that
is **not part of the slides** (e.g. a `.post-notes` block) containing:

- A suggested **caption** for the Instagram post.
- A set of **hashtags**.
- 2-3 posting **tips** (file size, screenshot method, bio link suggestion).

## Rules

- Every fact, number, count, and feature name on the slides must be real and
  verified against the repository. Never invent stats or content.
- If the repo or org has no discoverable brand (no logo, no colors), ask me for
  one preferred accent color + a heading font, or pick a clean, modern default
  and tell me what you assumed.
- Keep it fully offline/self-contained - the HTML must render correctly from a
  local file with no internet access.
- Do not pad slides with placeholder content; if you don't have a real fact for
  a slot, leave the slide out or reshape the arc rather than fabricate.
- Follow the repo's actual category counts and naming.

Audit and implement responsive design for `[page / component / layout]` in
this repository. The goal: a UI that works well at every screen size, built
mobile-first with fluid techniques, not breakpoint hacks.

## Steps

1. **Audit the current state** - Read the existing CSS/styling and identify:
   fixed widths, hardcoded pixel values, missing viewport meta tags, images
   without responsive handling, and layouts that break at narrow widths.
   Check the repo's existing breakpoint values and responsive utilities.
2. **Define the breakpoint strategy** - Use the repo's existing breakpoints
   if defined. If not, establish a standard mobile-first set: sm (640px),
   md (768px), lg (1024px), xl (1280px). Document the breakpoints for the
   team.
3. **Implement mobile-first** - Start with the smallest screen layout and
   add complexity as width increases. Use relative units (rem, em, %, vw)
   over fixed pixels. Apply fluid techniques: flexbox/grid for layout,
   clamp() for fluid typography, aspect-ratio for media.
4. **Fix layout issues** - Address: overflow at narrow widths, text that's
   too small to read, touch targets too close together, horizontal
   scrolling, images that stretch or crop poorly, and content that
   disappears at certain widths.
5. **Test at every breakpoint** - Manually verify (or use browser DevTools
   responsive mode) at each defined breakpoint and in between. Check:
   layout integrity, readability, touch target sizes (min 44x44px), and
   that no content is hidden or overlapping.
6. **Handle media and interaction** - Ensure responsive images with srcset
   or picture element, touch-friendly interactions (no hover-dependent
   functionality on touch), and appropriate input types on mobile (tel,
   email, number).

## Rules

- Never use `!important` to override responsive styles - fix the cascade
  instead.
- Never hide content at certain breakpoints unless there's a clear UX reason
  - content disappearing is a bug, not a feature.
- Never rely solely on hover states for important functionality - it doesn't
  exist on touch devices.
- If the repo uses a CSS framework (Tailwind, Bootstrap), use its built-in
  responsive utilities rather than custom media queries.

Design or refactor the client-side state management for this frontend app.
The goal: each piece of state has exactly one home and one owner, derived
data is computed rather than stored, and no component syncs state by hand.

## Steps

1. **Inventory existing state** - Find all state: component-local, lifted or
   context-based, global stores, URL, server cache. For each: who reads it,
   who writes it, and does it duplicate something else?
2. **Classify by kind** - Server data (fetched, cacheable - belongs in a
   query/cache library or equivalent, not hand-rolled stores), URL state
   (filters, tabs, pagination - belongs in the URL so it's shareable), true
   client state (form drafts, UI toggles), and derived values (compute during
   render via selectors - never store).
3. **Assign one home each** - Move server state out of manual stores into the
   cache layer; push shareable view state into the URL; keep local UI state
   local until two distant components genuinely need it. Delete duplicated
   copies and their sync effects.
4. **Simplify the toolkit** - Prefer the fewest mechanisms that work:
   built-in primitives first, then a store library only for genuinely global
   client state. Removing a library is a valid outcome.
5. **Handle the edges** - Loading/error states per query, optimistic updates
   with rollback, races on rapid refetches (cancel or supersede stale
   responses), persistence where required.
6. **Verify by behavior** - Walk the critical flows (filter, fetch, paginate,
   edit, refresh): state survives reload where expected, no stale renders, no
   double fetches, no lost updates. Prove with tests on the trickiest flows.

## Rules

- Stored derived state is a defect waiting to desync - compute it instead.
- Two sources of truth for the same fact must be merged, or one deleted.
- Any state you add must answer: who owns it, who may write it, and when is
  it invalidated?

Audit the UI of `[page / component / feature]` in this repository against the
project's own design system and conventions. Produce a prioritized list of
findings, each with a concrete fix that can be checked against the repo's
styles, tokens, and components.

## Define the scope first

Before auditing, state clearly:

1. **What is in scope** - the specific pages, components, or routes to cover.
2. **What is out of scope** - anything explicitly excluded.
3. **The design system in use** - Confirm which tokens, theme config, component
   library, or style guide the codebase follows. If none exists, say so and
   recommend one - do not invent one.
4. **The rendering context** - Browser targets, supported themes (light/dark),
   and any device-specific requirements the project cares about.

Do not begin the audit until the scope and design system are defined and
confirmed.

## Audit dimensions

For every in-scope element, check these dimensions in order. Stop on a broken
layout before moving to spacing nuance.

1. **Design system adherence** - Compare each component's styles (colors,
   font sizes, spacing, border radii, shadows) against the project's token
   system or established conventions. Flag every hardcoded value that bypasses
   the shared constants. Identify places where the codebase has invented its
   own values.

2. **Visual consistency** - Compare similar components and states side by side:
   primary/secondary buttons, form inputs, cards, badges, alerts, nav items.
   Check that hover, focus, active, disabled, loading, and error states are
   defined and look uniform across the UI. Find orphaned style variations that
   appear in only one component.

3. **Spacing and vertical rhythm** - Audit padding, margin, and gap values.
   Flag inconsistent spacing scales with no reason (e.g. 8px in one place,
   12px in another). Check vertical rhythm in text-heavy layouts. Verify
   alignment across grid, flex, and stacked layouts.

4. **Typography** - Verify heading hierarchy is logical with no skipped levels.
   Check that line-height, letter-spacing, and font-weight usage match the
   project's type scale. Flag text that overflows its container or truncates
   without an ellipsis or tooltip.

5. **Responsive behavior** - Trace layout behavior at 320px, 768px, 1024px,
   and 1440px by reading media queries and responsive styles (or screenshot if
   the agent can render). Flag overflowing containers, unreadable text, touch
   targets smaller than 44x44px, and breakpoints that appear to have been
   chosen without a strategy.

6. **Interaction states and feedback** - Confirm loading, empty, error, and
   success states exist and are styled consistently. Check that interactive
   elements give visible feedback on hover, focus, and press. Flag silent
   failures where the user gets no indication something happened.

7. **Icons, images, and media** - Confirm icons come from a single library or
   use a consistent stroke/fill style. Verify image sizes, aspect ratios, and
   placeholder/skeleton states are handled. Flag mixed icon sets or
   inconsistent image treatment.

8. **Theming** - If the project supports multiple themes, render or trace each
   component through every supported theme. Flag hardcoded colors that break in
   dark mode or components that ignore the theme variables.

## Method

1. **Read the style architecture first** - Find design token definitions, theme
   config, global styles, and any component library before auditing. Understand
   the system you are auditing against.

2. **Walk the component tree** - Read each in-scope component's styles (CSS
   modules, styled-components, Tailwind classes, or inline). Compare every
   value against the token system. Note each deviation with the specific
   file:line and value.

3. **Capture or trace at breakpoints** - If the agent can render or preview,
   capture the UI at 320px, 768px, 1024px, and 1440px. Otherwise, read the
   responsive styles and media queries to trace layout behavior at each
   breakpoint.

4. **Group findings by dimension** - Organize every finding under its audit
   dimension (spacing, typography, color, responsiveness, etc.), not as a
   flat list.

5. **Show the fix, not just the problem** - For each finding, cite file:line,
   state the current value, the correct value, and the exact code change
   needed. If a token should be used, name the token.

## Verification

Before reporting the audit complete, confirm each of these:

- [ ] Every finding cites a specific file:line, not a vague location.
- [ ] No finding invents a design token or convention that does not exist in
      the codebase.
- [ ] If a design system is in use, each finding is checked against it.
- [ ] Findings are prioritized: broken layouts and unreadable text first,
      minor spacing inconsistencies last.
- [ ] Intentional design choices (e.g. a hero heading that deliberately breaks
      the type scale) are not flagged unless they conflict with documented
      guidelines.
- [ ] If the UI is already consistent within scope, that is stated explicitly
      with what was verified, not padded with invented issues.

## Rules

- State the scope and design system before auditing. Do not audit a moving
  target.
- Never report "could be more consistent" without specifying what is
  inconsistent, where it is, and what the correct value should be.
- Never invent design tokens or conventions the codebase does not have. If
  there is no token system, say so and recommend one.
- Do not flag intentional, documented design choices as errors.
- Prioritize by user impact. A broken layout at mobile width is a higher
  priority than a 2px spacing inconsistency.
- If the UI is already consistent within scope, say so and list what was
  verified - do not invent issues to fill the report.

Diagnose and improve this site's Core Web Vitals (LCP, INP, CLS). Work from
measurements: identify the dominant problem first, fix it, re-measure.
Optimizing the wrong thing is wasted effort.

## Steps

1. **Measure the baseline** - Lab runs (Lighthouse against production-like
   builds) and field data (RUM/CrUX if available) per page template. Record
   LCP, INP, CLS with the offending elements identified.
2. **Attack LCP first if it lags** - Usual suspects in order: render-blocking
   CSS/JS, slow server response (caching, streaming SSR), unoptimized hero
   images (right format and size, preload/priority hints), late-discovered
   resources. Fix the biggest contributor, not everything at once.
3. **Then INP** - Profile long tasks on interaction: hydration storms,
   oversized JS payloads, synchronous layout thrash. Split tasks, defer
   non-critical work, reduce shipped JS, memoize expensive renders.
4. **Then CLS** - Images/video without dimensions, late-loading fonts (use
   `font-display` plus preload), injected content above the fold, animations
   on layout properties. Reserve space; animate transform/opacity only.
5. **Guard the wins** - Bundle-size budgets and performance assertions in CI
   (Lighthouse CI or equivalent), an enforced image pipeline, and a RUM
   dashboard so regressions are seen in the field, not just the lab.

## Output

A baseline-vs-after table per vital per page, the changes made ranked by
impact, and what remains with expected gains.

## Rules

- Never claim improvement without re-measuring under the same build and page
  conditions.
- Field data outranks lab data when they disagree - optimize what users
  experience.
- Once a vital is comfortably green, stop polishing it and move to the next.

Audit and improve this website's technical SEO. Work from verified
evidence, not guesses: a bot hasn't rendered or indexed a page just because
you typed a URL. Rank fixes by impact on indexing and ranking, implement
them, and re-verify.

## Steps

1. **Establish the baseline** - Determine the exact site (confirmed
   `robots.txt`, `sitemap.xml`, and canonical URLs, not assumptions). Crawl
   the live site - the production domain users reach, including trailing
   slash and `www` vs apex handling. Record key pages, their
   indexability, and current title/meta state.
2. **Crawlability & indexability** - Check `robots.txt` for blocked
   resources (CSS/JS/images shouldn't be blocked; stray `Disallow`s and
   `noindex` on pages that must rank are common bugs). Verify
   `sitemap.xml` lists the canonical page URLs, uses `lastmod` correctly,
   and is referenced from robots.txt. Flag duplication: near-identical
   URLs, parameter variants, and printer/mobile subdomains.
3. **Canonicalization** - Ensure every page has a self-referencing
   `rel="canonical"` and that `http`/`https`, `www`/apex, and trailing
   slash all resolve to one canonical form with a proper 301 redirect.
   Chase any redirect chains to their end and collapse them to a single
   hop. Confirm pages you don't want indexed are truly `noindex` and
   either disallowed or removable.
4. **Metadata & structured data** - Audit title and meta description per
   template: unique, correct length, keyword-relevant, matching the
   rendered page, not duplicated via the same CMS field feed. Add JSON-LD
   structured data for Organization, BreadcrumbList, and, where the page
   type warrants it, Article/Product/Faq. Validate every schema block
   against a schema validator and check with a rich-results test.
5. **On-page content & headings** - Confirm a single `h1` per page
   describing the page topic, a sane `h2`/`h3` hierarchy, and that
   target keywords appear in the title, headings, and body without
   stuffing. Flag empty pages, thin content, and missing/misleading
   alt text on meaningful images.
6. **Internal links & external signals** - Verify key pages are reachable
   via crawlable text links (not JS-only navigation), add descriptive
   anchor text, and fix broken internal links. Optionally review backlinks
   via a trustworthy source, but never suggest buying links.
7. **Speed, mobile, and Core Web Vitals** - Measure the same pages in the
   lab (Lighthouse) and field (CrUX if available) and flag LCP/INP/CLS,
   oversized images, render-blocking resources, and mobile rendering
   issues. Fix the biggest contributor first; re-measure under the same
   conditions.
8. **Guard the wins** - Add checks that stop regressions: a CI lint that
   fails on duplicate titles/meta, missing canonical, oversized images, or
   empty `h1`; and a recurring crawl (sitemap diff, robots.txt review,
   index-change alerts) so indexing problems surface early.

## Output

A baseline table per key page: indexable? canonical target, title/meta
status, headings, structured-data validation, speed metrics. Then the
changes made ranked by expected impact, with before/after evidence and the
remaining blocked-by-non-technical-work items.

## Rules

- Never claim a page is indexed, canonical, or blocked without verifying
  via the live server, the search engine's own tools, and a validator.
- Judge only against the production site users actually reach, not staging.
- Optimize pages people search for - not an arbitrary audit list.
- If content quality or rankings are the goal, say so and scope in the
  content work; this prompt is the technical foundation.

Create a CI/CD pipeline for **this** repository using GitHub Actions. Do not
ask which repo - use the current one. The pipeline must be fully automatic and
enforce the constraints below.

## Output

One or more workflow files under `.github/workflows/`. Prefer official
`actions/*` steps over third-party actions. If you write custom logic, use
bash with the GitHub CLI (`gh`) - no unchecked third-party actions.

## Default pipeline (adjust to the repo's actual stack)

- **CI**: on `push` and `pull_request` - install dependencies, run lint,
  format, type checks, and the test suite using the repo's own tooling.
  Cache dependencies where supported. Fail fast on the first broken job.
- **Coverage**: if the repo has a coverage tool, run it and upload the report.
- **Security**: run a dependency/secret scan if one is already configured;
  otherwise note it as a recommendation, don't add a heavy new tool without
  being asked.

## Hard constraints (non-negotiable)

- Never execute untrusted code in a privileged context. For pull requests from
  forks, use `pull_request_target` **only** if the workflow needs a
  write-scoped token, and in that case never `checkout` or run code from the
  PR - only read metadata and post statuses/comments. Say so in a header
  comment.
- Never string-interpolate user-derived values into `bash -c` or command
  strings that could be injected. Pass them via environment variables.
- Never commit secrets to the repository. Use repository secrets/variables for
  anything sensitive, and read them via `${{ secrets.X }}` or env vars.
- Pin third-party actions to a full-length commit SHA (not a branch/tag) or
  explain why an official `actions/*` tag is acceptable.
- Add `concurrency:` groups so rapid repeated events cancel or queue instead
  of running duplicate jobs.

## Verification (required before finishing)

1. Confirm each YAML file parses (e.g. `python -c "import yaml,sys; yaml.safe_load(open(...))"` or a YAML lint).
2. Extract each `run:` block and syntax-check with `bash -n`.
3. Dry-run any read-only logic against the real repo to confirm queries and
   commands return sensible results. Do NOT perform write operations during
   verification.
4. If the repo already has CI, ensure your pipeline does not duplicate or
   conflict with it - reconcile rather than replace.
5. Confirm commit-message style follows the repo's conventions (Conventional
   Commits) if committing.

Build a commit checklist for this repository: deterministic checks that fail
CI when derived artifacts drift out of sync. Repos rot through forgotten
bookkeeping, not bad intentions; make the bookkeeping unforgettable without
drowning contributors in noise.

## Steps

1. **Inventory the invariants** - Read the repo structure first and list
   every pair of artifacts that must agree: index files vs actual content,
   changelog vs newly added files, counts vs reality, naming conventions,
   folder vs section mappings. Each invariant becomes one check.
2. **Express checks as deterministic rules** - Every check must be a
   file-graph or diff fact that either holds or does not: "every X is listed
   in Y", "every added Z has a changelog entry". Reject vague style opinions;
   if a rule needs taste to evaluate, it is not a gate.
3. **Put logic in a script, not the workflow** - Implement the checks in a
   versioned, locally runnable script; keep CI as a thin job that invokes it.
   Minimal permissions, no third-party actions unless unavoidable, and lint
   the script itself.
4. **Scope additive rules by diff** - Rules about new content must use the
   merge-base diff against the target branch
   (`git diff --name-only --diff-filter=A <base>...HEAD`), so pre-existing
   content never triggers false positives and multi-file PRs work naturally.
5. **Make failures actionable** - Every failure names the exact fix: the
   missing entry, the expected line, the mismatched count. Print a pass/fail
   summary so authors can self-serve instead of ping-ponging with review.
6. **Wire enforcement deliberately** - Add the workflow, then make its job a
   required status check on the default branch. Decide explicitly whether
   admins can bypass (direct pushes) or everything goes through PRs, and
   state which in the PR description.
7. **Verify both directions before merging** - Run the suite green on the
   current state first; then prove each check fires by temporarily breaking
   one invariant at a time (unlisted file, missing entry, stale count). A
   gate that has never failed is untested code.

## Rules

- No gate you cannot run locally in one command.
- Document every gate in the contribution docs in the same PR that adds it.
- Keep the suite fast and quiet when green - gates that cry wolf get deleted.
- Enforcement changes are stated in the PR description, never snuck into an
  unrelated change.

Upgrade `[package]` from `[old version]` to `[new version]` in this repository.
Do this carefully: an upgrade is a code change with its own risk, not a
package.json edit.

## Steps

1. **Survey the blast radius** - Find everywhere the package is used: imports,
   config, build tooling, CI, docs. Read the code that depends on it so you
   know what behavior is actually relied on.
2. **Read the changelog** - Review the release notes/migration guide between
   the two versions. List the breaking changes, deprecations, and security
   fixes that apply to this repo's usage. Cite what you find - don't
   summarize from memory.
3. **Update the manifest** - Change the version in the appropriate lockfile/
   manifest. If the project uses a lockfile, update it through the project's
   tooling (e.g. `npm install`, `pip install`, `go mod tidy`) rather than by
   hand.
4. **Fix what breaks** - Run the test suite and the repo's checks. For each
   failure, read the actual API change and migrate the code properly. Do not
   disable tests or silence errors to make it pass.
5. **Verify behavior** - Exercise the affected paths beyond the tests where
   practical. Check that deprecated-but-warned usage is cleaned up.
6. **Document** - Note the upgrade in the changelog if the repo keeps one, and
   call out any breaking changes or behavioral differences for consumers.

## Rules

- Never upgrade just to be on the latest version - the upgrade must be
  justified (security, bugfix, feature, or explicit request).
- Never mix unrelated dependency changes into the same commit.
- If the new version needs a different runtime/Node/Python/Go version, stop
  and flag it instead of silently changing the environment.
- Verify with the repo's real checks; don't claim green CI you didn't see.

Use git bisect to find the exact commit that introduced `[bug / regression /
behavior change]`. The goal: pinpoint the introducing commit so the fix is
targeted, not a guess.

## Steps

1. **Reproduce the bug** - Before touching git, confirm you can reproduce the
   bug on the current code. Document the exact steps, commands, and
   inputs that trigger it. If you can't reproduce it, stop and clarify the
   symptoms.
2. **Find a known-good commit** - Identify a commit where the behavior was
   correct. Use git log to find a recent commit before the bug was reported,
   or use a release tag. Verify the behavior is correct at that commit
   (build and test at that point, or check out and run).
3. **Write a test or script** - Create a minimal, non-interactive script or
   test that fails when the bug is present and passes when it's not. This is
   your bisect script. It must be deterministic and fast. Examples: a
   specific assertion, a curl command that returns the wrong status, a
   command that exits non-zero on the bug.
4. **Run git bisect** - Start the bisect session: `git bisect start`,
   `git bisect bad` (current), `git bisect good <commit>`. Let git bisect
   run your script automatically: `git bisect run ./test-script.sh`.
5. **Identify the commit** - Git bisect will output the exact commit hash
   that introduced the bug. Read the commit message, the diff, and the
   author to understand what changed and why.
6. **Verify** - Confirm the bug exists at the identified commit and does not
   exist at the commit before it. Read the diff to make sure it explains
   the regression.

## Rules

- Never bisect with a manual "does it look broken?" check - the test must
  be automated and deterministic.
- Never skip verifying the bisect result - confirm the commit is actually
  the introducing change.
- If the bisect run fails (build errors at intermediate commits), use
  `git bisect skip` or choose a narrower range rather than aborting.
- If the bug is in a dependency, bisect the dependency separately, not this
  repo's history.

Help me with the git operation I describe in this repository. Work carefully:
git history surgery can destroy work. Verify your commands before running
them and prefer non-destructive operations.

## Ground rules

1. **Understand before acting** - Show me what the current state is
   (`git status`, `git log --oneline --graph`, relevant branches) and explain
   what the operation will do before you run anything irreversible.
2. **Never rewrite published history** - No `rebase`/`filter-branch`/force-push
   on commits that exist on the remote, unless I explicitly confirm I know the
   consequences. Prefer `revert` for committed-then-pushed mistakes.
3. **For local-only history** - Use `git rebase -i`, `git reset --soft`,
   `git commit --amend`, and `git reflog` to tidy local commits. Before a
   rebase, make sure my working tree is clean (or stash first) and show me
   the plan.
4. **Finding things** - Use `git bisect` to find the commit that introduced a
   bug (give me the good/bad start points and let me run each step if you
   need my input), `git blame` for line provenance, `git log -S/-G` for when a
   string changed, and `git reflog` to recover seemingly lost commits/branches.
5. **Recovery** - If work appears lost, check the reflog and dangling commits
   (`git fsck --lost-found`) before concluding it's gone. Never recreate work
   from memory when the original can be recovered.

## Rules

- Never force-push unless I explicitly ask.
- Never use `filter-branch` to scrub secrets from history on a shared repo -
  advise rotating the secret and using GitHub's secret-scanning/removal
  tooling instead.
- After any surgery, verify the result (`git log`, `git status`, tests) and
  show me the diff of what changed.

Create a GitHub Actions workflow for **this** repository that reserves
starter-labeled issues (`good first issue` and `help wanted`) for first-time
contributors. The workflow must run fully automatically with no manual
approval, and enforce the rules below. Do not ask the user which repo - use
the current one.

## Output

A single workflow file at `.github/workflows/good-first-issue.yml`, written
in bash using the GitHub CLI (`gh`), with **no third-party actions and no
`checkout` step** anywhere. Three jobs: a per-assignment guard, a per-PR
guard, and a periodic on-demand sweep that enforces the policy
retroactively.

## Configurable policy (use these defaults unless told otherwise)

- Labels to protect (reserved for first-timers): `good first issue` and
  `help wanted`
- Experienced contributors should be redirected to any **unreserved** issue
  (the old "pick a help wanted issue instead" advice no longer applies -
  `help wanted` is itself reserved)
- "First-time contributor" = has **0 merged PRs** authored by them in this
  repo (query via `gh pr list --state merged --author "<login>" --limit 1`;
  beware the `commits?author=` API 422ing for users with no GitHub activity
  - don't use it)
- Exempt from enforcement: repo owner and anyone with collaborator access
  (use `author_association` if available on the event, else the collaborators
  API `repos/{owner}/{repo}/collaborators/{login}` → 204 means exempt)
- Staleness window `GFI_STALE_DAYS`, default **14 days**: a first-time
  assignee who has no open PR referencing the issue after that long is
  unassigned and the issue returns to the pool

## Enforcement behavior

All comments (welcome, policy, close, stale) must spell out the **explicit
kinds of issues** the reserved labels cover - documentation, tests, small
bug fixes, and scoped UI/UX, performance, and devops chores - and, for
experienced contributors, point them at unreserved work (e.g. larger
features, architecture, security hardening, cross-platform/CI overhauls)
instead.

1. **When someone gets assigned to a protected issue** (trigger
   `issues: types: [assigned]`, only if the issue has either protected
   label):
   - Assignee is first-time → post a friendly welcome comment once (dedupe
     with a hidden HTML-comment marker in the comment body).
   - Assignee is experienced → remove them (`DELETE
.../issues/{n}/assignees`), post a polite comment explaining the policy,
     and **close without merging** any PRs authored by that person that
     reference the issue (find them via the issue's timeline
     `cross-referenced` events filtered to PRs and matching author).
2. **When a PR is opened that claims a protected issue** (trigger
   `pull_request_target: types: [opened, reopened]`): parse the PR body for
   claim refs ONLY - regex
   `(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)\s+#\d+`
   (case-insensitive) so a `#N` in prose or code fences is ignored. If any
   referenced issue has either protected label and the author is experienced →
   close the PR without merging + comment. Skip owners/members/collaborators.
3. **Periodic sweep** (trigger `schedule: cron: "0 */6 * * *"` **and**
   `workflow_dispatch` so it can be run on demand). It is the backstop that
   catches everything the event triggers miss, so it must do three things:
   - **Assignment enforcement**: search all open protected issues (union of
     both labels - note `gh search issues` ANDs multiple `--label` flags, so
     run one search per label and `sort -u`), and for any assigned to a
     non-exempt experienced contributor, apply the same unassign + comment +
     close-linked-PRs logic. This catches issues labeled after assignment and
     unassign/reassign dodging.
   - **Retroactive PR-claim sweep**: enumerate every open PR, extract claim
     refs from the body (same regex as rule 2), and close any PR by an
     experienced non-exempt author that claims a protected issue. This closes
     PRs opened **before** the workflow existed and authors who became
     "experienced" after opening their PR - the event trigger alone never
     sees either case.
   - **Staleness release**: for a protected issue held by a **first-time**
     assignee, find their last `assigned` timeline event (dedupe by
     assignee), and if it is older than `GFI_STALE_DAYS` **and** they have no
     **open** PR referencing the issue, unassign them (comment with a
     `good-first-issue-stale` marker) so the issue is freed up. Never release
     an assignee who has an open PR on the issue.

## Hard security constraints (non-negotiable)

- `pull_request_target` runs with a write-scoped token on fork PRs, so the
  workflow **must never checkout or execute code from the PR**. It may only
  read issue/PR metadata and write comments/unassignments/closes. Keep it
  that way and say so in a header comment. This is also why shared logic is
  duplicated inline across jobs instead of being factored into a script file
  that would require a checkout.
- Pass any user-derived values to `gh` via environment variables or shell
  variables - never string-interpolate them into commands that could be
  injected.
- Guard every `gh` write call with `|| true` so a race (already-closed PR,
  already-unassigned) can't fail the job.
- Add `concurrency:` groups (per issue / per PR / one shared sweep group) so
  repeated events can't double-comment.

## Permissions

`permissions: { issues: write, pull-requests: write }` and run with
`GH_TOKEN: ${{ github.token }}`, `GH_REPO: ${{ github.repository }}`.

## Verification (required before finishing)

1. Confirm the YAML parses.
2. Extract each `run:` block and syntax-check with `bash -n`.
3. Dry-run the read-only logic against the real repo to confirm: the
   merged-PR count query returns `0`/`1` for known users, the claim-ref
   regex extracts the right issue numbers from real PR bodies, the timeline
   cross-reference query works, and the sweep searches (both labels, plus the
   open-PR enumeration) return results. Do NOT perform any write operations
   during verification.
4. Confirm commit-message style follows the repo's conventions
   (Conventional Commits) if committing.

Help me resolve the GitHub issue I point you at (`OWNER/REPO#N`). The goal is
a pull request a maintainer merges on the first or second review, not a patch
that looks plausible. An issue is not resolved until the failing behavior is
gone, a regression test catches it, and the project's own checks pass.

## Steps

1. **Understand the ticket** - Read the issue body and every comment.
   Identify the expected behavior, the actual behavior, the platform or
   environment details, and any reproduction steps. Restate the ask in one
   sentence and list the files you expect to touch. If a bug report lacks
   repro steps, expected vs actual, or environment details, ask for the
   specific missing piece before proceeding. If the issue is ambiguous or its
   premise looks wrong, stop and ask rather than guessing.
2. **Read the room** - Read `CONTRIBUTING`, `README`, `CODE_OF_CONDUCT`, and
   the issue/PR templates. Identify the project's test runner, lint and
   format commands, and how CI is configured. Match existing code style and
   patterns. Check the issue timeline for linked PRs, branches, or comments
   that show the work is already in flight.
3. **Reproduce before you fix** - For a bug, reproduce the failure first and
   capture the actual output. For a feature request, capture the current
   behavior the issue wants changed. A failure you cannot reproduce is a
   failure you cannot claim to fix. Reproduce at the point of failure: a unit
   test, a script, or the described manual steps, whichever is closest to the
   reported behavior.
4. **Find the root cause, do not guess it** - Trace the path from the entry
   point to the failure. Use the debugger, `git log -S`, `git blame`, and
   adjacent code as evidence. State the root cause in one or two sentences and
   point at the exact line or commit. If your fix does not explain the
   reproduced failure, you have the wrong root cause.
5. **Plan the smallest change** - State precisely what will change and why it
   resolves the root cause. Prefer the smallest change that fixes the issue
   while staying consistent with the surrounding code. If the maintainable fix
   is larger, say so and outline it rather than silently inflating scope.
6. **Implement with a regression test** - Make the change and add a test that
   fails against the pre-fix code and passes with the fix. The test must
   encode the behavior in the issue, not a weaker version of it. Update
   existing tests only when the fix changes intended behavior; explain any
   such change. If a test is impossible, prove the fix manually and say in the
   PR exactly how to reproduce the proof.
7. **Run the project's full verification pipeline** - Run the test suite,
   linter, formatter, and type checks exactly as CI runs them, before and
   after the change. Paste the outputs. A change that passes a targeted test
   but breaks the full suite is not done.
8. **Commit and open the PR** - Commit with the project's message style
   (often Conventional Commits). In the PR body describe what the issue is,
   the root cause, the fix, and how you verified it, and reference the issue
   with a closing keyword (`Closes #N`, `Fixes #N`) only if it truly resolves
   it. Follow the PR template. If the repo requires tests or docs for
   user-facing changes, include them.

## Rules

- Never claim you ran a check you did not run, and never claim a bug is fixed
  without showing the reproduced failure is gone.
- Do not fix adjacent issues discovered along the way; note them in a comment
  or the PR body so the maintainer can decide, but keep this change focused
  on the issue.
- No unrelated refactors, formatting churn, or dependency bumps mixed into a
  fix.
- Do not force-push after review unless the project expects it; add commits in
  response to feedback.
- If your change makes an existing test or documented behavior stale, that is
  a signal you may have the wrong fix: re-examine the root cause before
  editing the test.
- Never resolve the issue by weakening or removing a guard, check, or test
  unless the issue explicitly asks for it and you can justify why it is safe.

## Verification (required before opening the PR)

1. The reproduction from step 3 changed from failing to passing.
2. The regression test from step 6 fails on the pre-fix code (or the manual
   proof is repeatable).
3. The project's full check pipeline from step 7 passes and the outputs are
   in the PR description.
4. The PR diff contains only what the issue asked for, plus tests and docs.

Triage the open issues in this repository. The goal is a backlog a
maintainer can act on in priority order, not a pile of "looked at it" noise.

## Steps

1. **Check reproducibility first** - For bug reports, confirm the report
   includes clear repro steps, expected vs actual behavior, and environment
   details. If any are missing, reply asking for the specific missing piece
   (name it, don't say "please provide more info") and label
   `needs-repro`/`needs-info` rather than guessing at the cause.
2. **Detect and link duplicates** - Search open and closed issues for the
   same root cause before triaging as new. Link duplicates to the canonical
   issue, summarize why they match, and close the duplicate with a pointer
   rather than leaving both open in parallel.
3. **Apply a severity/priority rubric consistently** - Use the repo's actual
   label set. If none exists, propose one (e.g. `severity: blocker/high/
medium/low`) rather than inventing ad hoc labels per issue. Justify the
   assigned severity in one line so the next person doesn't have to re-derive
   it.
4. **Flag good-first-issue candidates with mentoring notes** - When an issue
   is small, well-scoped, and doesn't require deep repo context, label it
   `good first issue` and add a short comment pointing to the relevant
   file(s) or pattern to start from - this is what makes the label honest
   instead of aspirational.
5. **Apply stale-issue policy, don't just silently close** - If the repo has
   a stale-bot policy, follow it. If not, propose one (e.g. ping after 60
   days of no repro/no response, close after 14 more days) and apply it
   consistently, always with a comment explaining why and how to reopen.
6. **Summarize the triage pass** - Report counts by label/severity, the
   duplicates merged, and any issues that need a maintainer decision you
   can't make (design questions, breaking changes, roadmap calls).

## Rules

- Never close an issue as invalid or duplicate without linking the reasoning
  or the canonical issue - a silent close reads as dismissive and loses
  context for whoever revisits it.
- Don't invent a label taxonomy that ignores one the repo already has;
  extend it, don't fragment it.
- Ask, don't assume, when severity or priority genuinely depends on product
  judgment rather than technical facts.

Help me contribute to the open-source project I point you at (`OWNER/REPO`).
Read the project's conventions before doing anything. A maintainer is going
to read your work - make it easy to review and merge.

## Steps

1. **Read the room** - Read `CONTRIBUTING`, `README`, `CODE_OF_CONDUCT`,
   `LICENSE`, and the issue/PR templates. Understand the project's workflow,
   its commit style, and what "done" looks like there. Check the issue tracker
   and recent PRs to see if the work is already in progress or requested.
2. **Scope the work** - Pick (or confirm) a specific, bounded task. For a
   first contribution, prefer a `good first issue` or `help wanted` if the
   project uses them. State exactly what you'll change and the files involved.
3. **Set up properly** - Fork, clone, and set up the upstream remote. Create a
   feature branch off the default branch. Install and run the existing tests
   to confirm the environment works before changing anything.
4. **Follow the project's rules** - Match the code style, keep changes
   minimal and focused on the task, add/update tests where the project
   expects them, and update docs if user-facing behavior changes.
5. **Verify** - Run the project's checks exactly as its CI does (lint, format,
   type checks, tests). A contribution that breaks CI is not done.
6. **Commit & push** - Commit with the project's message style (often
   Conventional Commits). Reference the issue in the PR body with a closing
   keyword (`Fixes #N`) only if it truly resolves it.
7. **Open the PR** - Use the template, describe what you did and why, note
   anything a reviewer should test, and answer review comments. Never argue
   with maintainers - address feedback or ask for clarification.

## Rules

- Never force-push a PR branch after review without being asked; prefer
  adding commits or amending only when the project expects it.
- Never submit a PR with unrelated changes, dependency bumps, or formatting
  churn mixed in.
- Don't claim you ran tests you didn't run. Verification must be real.

Review this project's maintenance setup and produce a plan that keeps it
sustainable: less noise, more automation, documented boundaries, and a path
for others to take over. Recommend changes that are actionable in this repo,
not generic advice.

## Steps

1. **Read the current setup** - Read CONTRIBUTING, issue and PR templates,
   workflows, and recent maintainer activity. Understand what pulls the
   project's attention today and what is manual.
2. **Audit the noise** - Find the repetitive sources of maintainer work:
   unlabeled issues, duplicate questions, stale PRs, and unclear
   contribution expectations. Quantify what you can (for example, issues
   submitted without the template filled in).
3. **Make guidelines filter, not block** - Amend CONTRIBUTING.md so a new
   contributor knows exactly what a good issue or PR looks like, what needs
   reproducing, and what types of change will be declined. Write decline
   reply templates that are respectful and specific, and reuse them.
4. **Automate the tedious parts** - Propose concrete automations that exist
   today: stale-bot or label automation, CI gates that check the cheap
   stuff, release and version tooling, and dependency updates. Wire them
   into the repo's actual CI files, not hypothetical ones.
5. **Set expectations publicly** - Produce a short roadmap or maintenance
   policy that says what is accepted, what is not, and how fast anything
   gets reviewed. Communication that sets expectations reduces repeated
   asks.
6. **Reduce the bus factor** - Identify every task and document that only one
   person can do. Produce an ownership map: which areas need another named
   person or at least written ownership notes, who can merge, and what a
   successor needs to run a release.

## Verification

- [ ] Every recommended automation maps to a change in this repo's CI or
      config files, not a generic suggestion.
- [ ] CONTRIBUTING changes cover the top noise sources found in step 2.
- [ ] Decline templates are written and stored where contributors will see
      them (a templates dir, or linked from CONTRIBUTING).
- [ ] The bus-factor audit names at least one single-owner area and what the
      fix is.
- [ ] No recommendation depends on the maintainer working more hours - every
      one reduces or redistributes load.

## Rules

- Never propose automation you have not verified exists; mark custom
  automations as "needs a custom action" if so.
- Never add process that costs more than the noise it removes.
- Never write a decline template that is curt or dismissive.
- Keep recommendations scoped to this repo; do not drift into how to run
  every open source project ever.

You are a senior software engineer reviewing a GitHub Pull Request.

Your job is to determine whether the changes are correct, safe, maintainable, and consistent with the existing codebase.

You are **not** here to generate as many comments as possible.

Your goal is to identify the relatively small number of things that a good human maintainer would genuinely want the author to know before merging.

## 1. Your mindset

Review the PR as if you are a member of the project's engineering team.

You have read the repository before.

You understand its conventions.

You care about the long-term health of the codebase.

You are not trying to demonstrate how much you know.

You are not trying to find something wrong with every file.

You are not trying to make the review look comprehensive.

A PR with zero comments can be a completely successful review.

A PR with one excellent comment is better than a PR with fifteen mediocre ones.

Optimize for signal over coverage over verbosity.

## 2. Understand the repository before judging the PR

Never review the diff in isolation when surrounding context is available.

Before forming conclusions, inspect the relevant parts of the repository.

Understand, where applicable:

- Project architecture
- Relevant modules
- Existing abstractions
- Data flow
- Error handling
- Authentication/authorization
- API contracts
- Database behavior
- State management
- Testing conventions
- Dependency usage
- Configuration
- Existing implementations of similar functionality

The repository's existing behavior is evidence.

Do not recommend a change merely because you personally prefer another architecture or coding style.

For example, if the repository consistently uses a particular pattern, don't flag a PR for using that pattern simply because you would design it differently.

## 3. Understand the PR's intent

Before reviewing individual lines, determine:

- What is this PR trying to accomplish?
- What behavior is changing?
- What assumptions does the implementation make?
- What parts of the system are affected?
- What could realistically break?

Read:

1. PR title
2. PR description
3. Changed files
4. Relevant surrounding code
5. Existing tests
6. Existing PR discussion/review comments

Only then begin evaluating individual changes.

## 4. What you should look for

Prioritize issues in roughly this order:

### Critical

- Security vulnerabilities
- Data corruption or loss
- Authentication/authorization bypasses
- Severe correctness bugs
- Production-breaking behavior
- Catastrophic concurrency issues

### High priority

- Incorrect behavior
- Broken edge cases with realistic likelihood
- Breaking API/interface changes
- Incorrect assumptions about existing behavior
- Significant race conditions
- Serious performance regressions
- Incorrect error handling
- Reliability problems

### Medium priority

- Missing important validation
- Meaningful maintainability problems
- Missing regression coverage for risky behavior
- Incorrect integration behavior
- Architectural inconsistencies that will create real problems

### Low priority

Only mention these when they have genuine value:

- Minor maintainability concerns
- Small inconsistencies
- Non-obvious readability problems

### Usually ignore

Do not comment on:

- Personal style preferences
- Trivial naming preferences
- Formatting
- Things already enforced by linters
- Nitpicks
- Hypothetical problems with no plausible impact
- "You could also..."
- Alternative implementations that are merely different
- Compliments that don't communicate useful information

## 5. The evidence rule

Never make a review comment based solely on intuition.

Before commenting, answer:

> What specifically is wrong?

Then:

> What concrete behavior does this cause?

Then:

> Can I point to evidence in the repository, PR, tests, API contract, or language/runtime behavior?

If you cannot establish a concrete problem, investigate further.

If the concern remains speculative, do not present it as a defect.

Do not invent:

- Requirements
- APIs
- Files
- Tests
- Runtime behavior
- User expectations
- Performance characteristics
- Security guarantees

If you don't know, say so internally and investigate rather than guessing.

## 6. Review the changed code in context

A changed line may look suspicious while being completely correct because of surrounding code.

Conversely, a seemingly harmless line may introduce a bug because of something elsewhere in the system.

Therefore:

**Trace behavior, don't just inspect syntax.**

For a potentially problematic change, follow the relevant path through the codebase.

For example:

```text
input
  ↓
validation
  ↓
business logic
  ↓
state/database mutation
  ↓
response
```

Determine where the actual failure occurs.

## 7. Think adversarially about correctness

For meaningful changes, mentally test:

- Empty input
- Null/undefined values
- Boundary values
- Unexpected input
- Duplicate requests
- Concurrent requests
- Failed network calls
- Partial failures
- Retries
- Missing permissions
- Stale state
- Invalid state
- Large inputs
- Unexpected ordering
- Backwards compatibility

You don't need to mention all of these.

Only raise the cases that reveal a real problem.

## 8. Security review

For security-sensitive code, explicitly consider:

- Authentication
- Authorization
- Input validation
- Injection
- Secret exposure
- Sensitive data leakage
- Access control
- Unsafe deserialization
- File/path handling
- Dependency risks
- Trust boundaries
- Client/server assumptions

Do not call something a security vulnerability merely because it is theoretically possible.

Establish the actual attack or failure path.

## 9. Concurrency and state

When code involves shared state, asynchronous operations, databases, queues, caches, or distributed systems, consider:

- Race conditions
- Duplicate writes
- Lost updates
- Stale reads
- Atomicity
- Transaction boundaries
- Retry behavior
- Idempotency

Again, only comment when there is a concrete failure mode.

## 10. Tests

Evaluate whether the PR's tests meaningfully protect the changed behavior.

Do not automatically request tests for every change.

A useful test comment explains:

- What behavior isn't covered
- Why that behavior matters
- What regression the test would prevent

Bad:

> Please add more tests.

Better:

> This path now treats a failed refresh as an empty result, so the existing test won't catch the regression where a transient auth failure silently logs the user out. I'd add a case for the refresh request failing here.

## 11. Don't repeat existing discussion

Before posting a comment, check the PR conversation.

Do not:

- Repeat an issue that has already been raised
- Re-ask an answered question
- Re-report something the author already fixed
- Ignore an explanation from the author
- Contradict another reviewer without evidence

If the author has already addressed a concern, update your understanding.

## 12. Comment threshold

Before leaving a comment, ask yourself:

> Would I actually interrupt a developer's work to tell them this?

If the answer is no, don't comment.

Then ask:

> Does this comment identify something actionable?

If not, don't comment.

Then ask:

> Is this actually caused by this PR?

If not, don't comment.

Then ask:

> Is this more than a personal preference?

If not, don't comment.

A useful mental filter is:

```text
Is it real?
    ↓
Is it caused by this PR?
    ↓
Does it matter?
    ↓
Can I explain why?
    ↓
Can the author act on it?
    ↓
COMMENT
```

If any important step fails, keep investigating or stay silent.

## 13. Writing style

Your comments should sound like an experienced developer talking to another developer.

Be:

- Direct
- Specific
- Concise
- Technical when necessary
- Conversational
- Respectful
- Proportionate to the problem

Avoid sounding like:

- A corporate consultant
- A textbook
- A code-analysis report
- A chatbot
- A teacher grading homework
- A marketing assistant

Do not over-explain obvious things.

Do not turn a two-line observation into a paragraph.

Do not use excessive headings.

Do not use emojis.

Do not add generic praise.

Do not write:

> Great job on this implementation! I noticed a potential issue that might be worth considering...

Instead, write:

> This can race when two requests hit this path concurrently. The check happens before the insert, so both requests can pass it. Can we make this atomic?

## 14. Avoid stereotypical AI language

Do not repeatedly use phrases such as:

- "I noticed that..."
- "It might be worth considering..."
- "Great job!"
- "Overall, this is a solid implementation."
- "One potential concern..."
- "This is a crucial improvement..."
- "I would recommend..."
- "It's important to note that..."
- "Could you please consider..."
- "This could potentially..."
- "As an AI..."

Especially avoid repeating the same sentence structures across comments.

Natural technical communication is usually simpler.

Instead of:

> One potential concern that might be worth considering is that this implementation could potentially result in...

Say:

> This can return stale data after a retry because the cache isn't invalidated here.

## 15. Don't pretend to be human

The objective is to produce natural, high-quality engineering communication.

Do **not** falsely claim personal experiences such as:

- "I've seen this happen before."
- "I've run into this issue myself."
- "In my experience..."

Do not fabricate human identity, testing, execution, or observations.

Natural writing does not require deception.

Simply communicate the technical observation directly.

## 16. Comment structure

A good review comment usually follows:

```text
Problem → consequence → suggested direction
```

Example:

> This deletes the cache before the database update succeeds. If the update fails, the next request rebuilds from the old value and repopulates the cache with stale data. I'd invalidate only after the transaction commits.

Do not force this structure when it would make the comment unnatural.

Sometimes one sentence is enough.

## 17. Use code when useful

If a small code example makes the problem obvious, include it.

Don't include large rewrites.

Don't solve the entire PR for the author unless necessary.

Prefer:

> Could this happen after the transaction commits instead?

over dumping an entire alternative implementation.

## 18. Severity

Internally classify each issue as:

- `blocking`
- `important`
- `minor`
- `nit`

Only expose severity when the GitHub review system requires it.

Be conservative.

A minor issue should not sound like a production incident.

A real security issue should not be softened into a casual suggestion.

## 19. Review summary

After evaluating the PR, produce a concise summary.

The summary should state:

- Whether there are blocking concerns
- The most important issues found
- Whether the implementation otherwise appears sound
- Any meaningful testing gap

Do not write a generic essay about the PR.

Bad:

> Overall, this PR demonstrates a thoughtful approach and introduces several exciting improvements to the codebase...

Better:

> The main issue is the transaction ordering in `X`, which can leave the cache stale after a failed write. Aside from that, the flow looks consistent with the existing implementation, and the new tests cover the main path.

If there are no meaningful issues:

> I don't see any blocking issues in this PR. The changed path is covered by the existing tests and looks consistent with the surrounding implementation.

That's enough.

## 20. Final decision

Your final internal decision should be one of:

```text
APPROVE
REQUEST_CHANGES
COMMENT
```

### APPROVE

Use when:

- No meaningful correctness/security/reliability issues exist
- The implementation is reasonable
- Testing is adequate for the risk

### REQUEST_CHANGES

Use when:

- There is at least one issue that should be fixed before merging
- The issue is concrete and significant

### COMMENT

Use when:

- There are useful observations
- But none clearly warrant blocking the PR

Do not request changes merely because the implementation isn't your preferred approach.

## 21. Final self-check

Before submitting the review, silently ask:

### Correctness

- Did I understand what the PR actually changes?
- Did I inspect enough surrounding code?
- Is every issue I raised real?

### Relevance

- Is each issue caused by this PR?
- Does each issue matter?

### Evidence

- Can I explain exactly why each issue occurs?
- Did I avoid assumptions?

### Communication

- Is every comment concise?
- Does it sound like a developer?
- Did I avoid generic AI phrasing?
- Did I avoid unnecessary praise?
- Did I avoid repeating myself?

### Restraint

- Am I commenting because something is genuinely wrong?
- Or because I feel like I need to produce a comment?

If the latter, **don't comment.**

The best automated review is often the one that says less.

## Core principle

You are not a comment generator.

You are a maintainer.

Read the code. Understand the intent. Find what actually matters. Explain it clearly. Then stop.

Automate the release process for this repository. The goal: a CI-driven
pipeline that versions, tags, changelogs, and publishes releases
consistently, with no manual steps that can be forgotten.

## Steps

1. **Understand the current process** - Read the existing release-related
   files: CHANGELOG.md, package.json version fields, any existing CI
   workflows, Makefile targets, and publish scripts. Understand how releases
   happen today (manual, semi-automated, or not at all).
2. **Choose a versioning strategy** - Based on the project type, pick the
   right approach:
   - **Semantic Versioning (SemVer)** - for libraries and packages with a
     public API (MAJOR.MINOR.PATCH)
   - **CalVer** - for applications with date-based releases
   - **Keep a Changelog** format for the CHANGELOG
     Document the chosen strategy in the README or CONTRIBUTING.
3. **Set up version bumping** - Configure a tool to automate version bumps:
   `semantic-release`, `release-please`, `changesets`, `bump2version`, or
   a custom script. The tool should: read conventional commits to determine
   the version bump type, update version fields in all relevant files, and
   generate or update the CHANGELOG.
4. **Automate tagging and GitHub releases** - When a version is bumped:
   create a git tag, push it, and create a GitHub release with release notes
   auto-generated from commits since the last tag. Use the repo's CI
   platform (GitHub Actions).
5. **Automate publishing** - If the project publishes to a registry (npm,
   PyPI, crates.io, etc.), add a publish step to the release workflow that
   triggers after tagging. Use secrets for credentials, never hardcode them.
6. **Verify** - Create a test release (on a fork or pre-release tag) to
   confirm the full pipeline: version bump, changelog, tag, GitHub release,
   and publish all work end-to-end.

## Rules

- Never hardcode version numbers in the release workflow - the tool must
  calculate them from commits or config.
- Never skip the changelog step - users and contributors rely on it.
- Never publish to a public registry without a tag and release notes.
- If the project has multiple publish targets (e.g. npm + Docker), all must
  be part of the same release workflow.

Build `[the mobile feature]` for this project and prove it works on a real
device or emulator for each supported platform. The goal: a feature that
survives the conditions real apps face - offline, permission denied,
background and restore, and platform quirks - not one that only renders
in a hot-reload session.

## Define the scope first

1. **Platforms** - Which platforms are in scope (iOS, Android, both) and what
   OS version floor applies. State the devices and OS versions you will
   verify on.
2. **The feature's requirements** - The exact behavior, inputs, and outputs,
   plus the defined offline and error behavior when a required dependency is
   unavailable.
3. **What is out of scope** - Platform-specific workarounds for platforms out
   of scope, store submission metadata, and analytics.

## What to produce

1. **The implementation** - Screen and flow code, state, and data layer for
   the feature, following the project's existing navigation, state, and
   styling conventions. Cite the files you changed.
2. **Permission handling** - Every permission the feature needs, when it is
   requested, what the denied path does, and why each permission is
   necessary. No silent crash on denial.
3. **Connectivity behavior** - What happens on the happy path, offline, and
   when a request times out or returns an error. Retry or cached state must
   be explicit, never accidental.
4. **Deep links and lifecycle** - How the feature behaves when opened from a
   deep link, backgrounded, killed, and restored. Cold-start state must be
   defined.
5. **Platform verification matrix** - A table of what was tested on which
   platform, device, and OS: launch, happy path, permission denied, offline,
   background/resume, and any platform-specific quirks found.

## Method

1. **Read the mobile project's conventions** - Navigation, state management,
   styling, and existing platform-specific code. Follow them.
2. **Fake the dependencies first** - Wire the feature against explicit
   interfaces so connectivity, permissions, and deep links can be exercised
   deterministically in tests and on simulators.
3. **Build the happy path, then the failure paths** - Implement the flow,
   then make denied permissions, offline, and timeout each produce a
   defined state.
4. **Verify on each platform** - Run on every declared platform: a real
   device if possible, otherwise the platform emulator at a realistic OS
   version. Exercise airplane mode, permission revocation, background/kill,
   and deep link entry.

## Verification

- [ ] The feature runs on every declared platform, proven by a run log per
      platform with the OS and device named.
- [ ] Permission denied produces a handled state (message, fallback, retry),
      never a crash.
- [ ] Offline behavior is verified with airplane mode on, and the state
      restores correctly when connectivity returns.
- [ ] Deep link entry and background/resume are tested and behave per spec.
- [ ] The test suite passes and covers the failure paths, not just the happy
      path.

## Rules

- Never ship a platform you have not run and seen behave.
- Never request a permission you cannot justify in the verification matrix.
- Never let a network failure surface as an unhandled error screen.
- If behavior differs by platform, handle it explicitly and note it - do not
  paper over it.

Improve `[what is slow: startup, scrolling, bundle size, memory, or network]`
for this mobile project. Measure each problem on a real device or emulator
first, identify what actually costs you, fix the few things that matter, and
prove the result with the same measurement method before and after.

## Steps

1. **Establish the baseline** - Measure the current state on a device or
   emulator with developer options enabled: cold and warm startup, scroll
   frame rate, app size at build output, and, if requested, memory and
   network profile. Record the tool and setup used so results are
   reproducible.
2. **Profile, don't guess** - Use the platform profiler (Android Profiler,
   Instruments, React Native or Flutter DevTools, or the framework's own
   tools) to find what actually costs time or bytes. A claim without a
   profile data point is a guess.
3. **Fix the real costs** - Apply the smallest fix that targets a measured
   bottleneck: lazy loading, image and asset handling, list virtualization,
   expensive work off the main thread, or fewer and smaller requests. Prefer
   changes that move the measured number.
4. **Re-measure identically** - Repeat the same measurement with the same
   tool and setup. Report before and after numbers and the delta - and be
   honest if a change did not move the needle.
5. **Guard the win** - Add a regression guard where practical: a size check, a
   CI performance threshold, or a test that fails when the metric regresses.

## Verification

- [ ] A reproducible baseline exists before any change.
- [ ] Every fix is tied to a profile data point, not a suspicion.
- [ ] Before and after were measured with the same tool and setup, and the
      delta is reported.
- [ ] Targets are stated (for example "cold start under 2s on a mid-range
      device") and checked against the after measurement.
- [ ] A regression guard is in place, or a reason is given why one is not.

## Rules

- Never optimize a path you have not measured on the target platform type.
- Never claim a win without identical before/after measurement.
- Never ship a size or memory regression to fix a startup one without saying
  so.
- Prefer a few measured wins over many speculative micro-optimizations.

Audit the UI of `[screen / flow / feature]` in this mobile project against the
platform conventions it must run on (iOS and/or Android) and the project's own
design conventions. Produce a prioritized list of findings, each with a
concrete fix that can be checked against the codebase - not a style wishlist.

## Define the scope first

1. **Platforms and devices** - Which platforms are in scope, the OS version
   floor, and the concrete devices and screen sizes to audit (small phone,
   large phone, tablet if in scope).
2. **Screens and flows** - The specific screens, routes, and flows to cover.
3. **Design conventions in use** - The tokens, theme, and component
   conventions the project follows. If none exist, say so and recommend one; do
   not invent one.
4. **Out of scope** - Anything explicitly excluded.

Do not begin until the scope and conventions are defined and confirmed.

## Audit dimensions

For every in-scope screen, check these dimensions in order. Stop on a broken
layout before moving to spacing nuance.

1. **Platform conventions** - Layout, controls, and navigation follow the
   platform idiom (iOS or Android): tab bar vs bottom nav, back affordance,
   swipe-back, pickers and dialogs, feedback patterns. Flag inverted or mixed
   conventions.
2. **Touch targets and hit areas** - Every interactive element is at least
   44x44 pt (iOS) / 48 dp (Android), with the real tappable bounds equal to or
   larger than the visual bounds, never smaller. Flag undersized targets and
   overlapping hit areas.
3. **Safe areas and cutouts** - Content clears the notch, camera cutout,
   status bar, home indicator, and rounded corners on the declared devices.
   Flag layouts that assume a full rectangle.
4. **Layout across sizes, density, and orientation** - Check on the declared
   devices at the densities they actually render (@1x/@2x/@3x), portrait and
   landscape. Flag clipped text, off-screen content, and fixed-pixel layouts
   that break on a smaller device.
5. **Keyboard and input** - Focused fields are never obscured by the keyboard,
   the layout responds when the keyboard opens, and fields use the right input
   type (email, number, phone) so the correct keyboard appears.
6. **States and feedback** - Loading, empty, error, success, offline, and
   retry states exist and are consistent. Interactive elements give visible
   feedback on tap; silent failures are flagged.
7. **Accessibility** - The UI holds at larger font and dynamic-type scales
   without clipped text, contrast meets the platform minimum, and every element
   is reachable by screen reader and keyboard. Flag touch-only dependencies.
8. **Theming** - If the project supports light/dark (or more) themes, each
   screen is checked in every supported theme. Hardcoded colors that break a
   theme are flagged.

## Method

1. **Read the design architecture first** - Find the token definitions, theme,
   and shared components before auditing. You audit against the project's own
   system, not an invented one.
2. **Read each screen's layout and style code** - Note dimensions, colors, and
   constraints with the specific file:line and value for every deviation.
3. **Run it, do not just read it** - On each declared platform, run the app on
   a device or simulator at the declared OS, in portrait and landscape, at the
   large font scale and in each theme. Capture screenshots as evidence.
4. **Group findings by dimension** - Organize everything under its audit
   dimension, not as a flat list.
5. **Show the fix, not just the problem** - For each finding: file:line, the
   current value, the correct value, and the exact change. If a token or shared
   component should be used, name it.

## Verification

- [ ] Every finding cites a specific file:line, not a vague location.
- [ ] No finding invents a platform or design convention the project does not
      have; missing conventions are reported, not assumed.
- [ ] Findings are prioritized: broken layouts, unreadable text, and
      unreachable controls first, minor spacing and typography nits last.
- [ ] Each platform in scope was run (device or simulator), not only read in
      code.
- [ ] Touch targets, safe areas, and large font scale were checked on every
      in-scope screen.
- [ ] Intentional, documented design choices are not flagged unless they
      conflict with a platform requirement.
- [ ] If the UI already meets the conventions within scope, that is stated
      explicitly with what was verified, not padded with invented issues.

## Rules

- State the scope, platforms, devices, and conventions before auditing. Do not
  audit a moving target.
- Never report "could be more consistent" without specifying what is
  inconsistent, where it is, and what the correct value should be.
- Never invent tokens, components, or platform guidelines the project does not
  have.
- Do not flag intentional, documented design choices as errors.
- Prioritize by user impact: a clipped screen at large font scale outranks a
  2pt spacing nit.
- If the UI is already consistent within scope, say so and list what was
  verified - do not invent issues to fill the report.

Overhaul the UI of `[feature / the whole app]` for this mobile project. Define
what the target UI must be, reimplement the screens, and prove the result on
every declared platform with before/after evidence - preserving the app's
behavior, state, and data flows.

## Define the target first

1. **Scope** - Which screens and flows are overhauled, and what stays
   untouched.
2. **Design direction** - The target look: tokens, layout, typography, motion
   to adopt. State it explicitly so the work can be checked against it; if the
   project has a design system, it is the baseline.
3. **Platforms and devices** - The platforms, OS version floor, and devices
   used to verify.
4. **Behavior constraints** - What must not change: state, data, navigation
   paths, offline and permission behavior. An overhaul is visual, not
   functional, unless the change is declared up front.
5. **Out of scope** - Store submission, content copy, and feature work.

## What to produce

1. **Target design spec** - The decisions written down: tokens, spacing scale,
   type scale, component patterns, motion, theming. Short enough to hold in
   mind, exact enough to check a screen against.
2. **Token layer** - The tokens and components introduced or changed first, so
   screens compose from them rather than diverge.
3. **Reimplemented screens** - Every in-scope screen rebuilt on the new layer,
   with file:line for each change.
4. **Preserved behavior** - A statement of which behaviors, states, and flows
   were confirmed unchanged, and how.
5. **Platform verification matrix** - A table of every in-scope screen per
   platform, device, OS, and theme, each row with a before and after capture
   and a pass/fail against the target spec.

## Method

1. **Baseline first** - Capture the current state of every in-scope screen on
   each declared platform before touching code. This is the "before" half.
2. **Read the current design architecture** - Tokens, shared components, and
   conventions. The overhaul is built on the project's own system.
3. **Build the token layer before screens** - Establish tokens and components
   first, then compose screens from them. Never hand-style a screen while the
   shared layer is missing.
4. **Rebuild screens, then verify behavior** - Reimplement the screens, then
   run the app and re-check the preserved behaviors and states, not just the
   new look.
5. **Verify on each platform** - Run every declared platform in each theme and
   at the large font scale at minimum, and capture the "after" shots. An
   overhaul is done only when its spec is demonstrated on the device.

## Verification

- [ ] Before and after captures exist for every in-scope screen on every
      declared platform, taken the same way.
- [ ] The target design spec is stated before implementation, and each screen
      is checked against it.
- [ ] All preserved behaviors (state, navigation, offline, permissions) are
      confirmed unchanged, with how they were confirmed.
- [ ] The app runs on every declared platform in each theme and at the
      declared accessibility scale.
- [ ] Tests pass and cover the flows the overhaul touched.
- [ ] No screen was hand-styled around a missing token or component; the
      shared layer is in place first.

## Rules

- Never change a behavior you cannot show still works. Verified expectations,
  not vibes.
- Never hand-style a screen around missing tokens; build the shared layer
  first.
- Never call it an overhaul when only one screen renders in a hot-reload
  session.
- Never claim a win without before and after evidence generated the same way.
- If a screen already meets the target spec, say so with evidence rather than
  changing it for change's sake.

Turn `[the website]` into `[the mobile app]`. Decide the adaptation strategy
from the website's actual architecture, then build and verify the app on the
declared platforms. The strategy is a decision, not a default.

## Decide the strategy from the code first

1. **Read the website's architecture** - Stack and framework, server-rendered
   vs client-rendered, auth and session handling, API surface and contracts,
   state management, and how the UI is styled. Cite what you found.
2. **Then choose the approach, and justify it for this codebase, not in
   general**:
   - **Thin wrapper** - a native shell (WebView) around the existing
     responsive web UI, fitting a site that is server-rendered or already a
     working PWA and whose priority is reach on the store shelves.
   - **Shared-logic re-implementation** (React Native, Flutter, or native)
     keeping the API and data contracts while rebuilding UI in platform
     components, fitting a site whose offline, performance, or platform-feel
     demands are core.
   - **Native from the start** - when offline-first, push, and sensors are
     hard requirements; say which requirement broke the cheaper options.
   - A rejected option names the concrete mismatch from the architecture you
     read, not taste.
3. **Also decide the delivery** - app store on both platforms, one platform,
   or web-only install. State it; it changes what must be proven.

## What to produce

1. **The strategy decision** - The approach, the delivery, and the rationale
   grounded in the architecture you read.
2. **The app** - The shell, navigation, screens, and state for the mobile
   experience, following the chosen approach and the project's conventions.
3. **Auth and session** - Sign-in flows that survive the app's offline and
   background life cycle, consistent with the site's existing auth.
4. **Online and offline behavior** - What works offline, what degrades, and
   how state resolves when connectivity returns.
5. **Platform verification matrix** - A table of the app per platform, device,
   and OS: launch, happy path, offline, background and resume, and any
   platform-specific quirks found.

## Method

1. **Read the site before choosing an approach** - The architecture pass comes
   before any decision, and the decision cites it.
2. **Reuse what the site already solves** - API contracts, auth, data models,
   and existing responsive layout (in a wrapper). Do not reimplement what
   already exists.
3. **Define the mobile behaviors** - Offline, background, permission, and deep
   link behavior, as the chosen approach handles them. State them.
4. **Build the smallest thing that proves the approach** - The shell and one
   core flow verified on a device first, then the rest.
5. **Verify on each platform** - For each declared platform, run the app on a
   real device or emulator: launch, happy path, offline, background and
   resume.

## Verification

- [ ] The strategy decision cites the website's actual architecture with
      evidence, not generalities.
- [ ] The app runs on every declared platform, with a run log naming the OS
      and device.
- [ ] A core flow works offline (or explicitly degrades) and recovers when
      connectivity returns.
- [ ] Auth and session behave consistently with the site and survive an app
      restart.
- [ ] No expensive reimplementation rests on taste alone; rejected options
      name the concrete mismatch.
- [ ] The test suite passes.

## Rules

- Never pick the strategy before reading the website's architecture.
- Never reimplement what the site already solves without saying what it buys
  you.
- Never ship a platform you have not run.
- Never claim "works just like the website" for behaviors you did not verify
  offline and after background.

Implement the requested authentication/authorization for this application.
Auth bugs are catastrophic and subtle; follow established patterns exactly
and verify each property with tests.

## Steps

1. **Choose the right pattern** - Server-side sessions (httpOnly cookie) for
   server-rendered apps; short-lived access tokens plus refresh rotation for
   APIs/SPAs; OAuth/OIDC through a maintained library for third-party login.
   Justify the choice; never roll your own crypto or protocol.
2. **Store credentials properly** - Passwords hashed with argon2id/bcrypt
   (never MD5/SHA alone), constant-time comparisons, no plaintext anywhere
   including logs. When migrating hash formats, rehash on next successful
   login.
3. **Harden token/session handling** - Secure, httpOnly, SameSite cookies;
   CSRF protection for cookie-authenticated mutations; rotation on privilege
   change; a revocation story for stolen sessions; sane expiry.
4. **Authorize on the server, everywhere** - Every endpoint checks identity
   and permission server-side (deny by default); object-level checks on every
   resource access to stop IDOR; admin routes behind explicit role checks.
   Hiding UI elements client-side is cosmetic, never the control.
5. **Cover the account lifecycle** - Registration with email verification,
   login rate limiting with lockout/backoff, password reset via single-use
   expiring tokens that invalidate existing sessions, logout everywhere.
6. **Test the properties** - Automated tests: unauthenticated access denied,
   cross-user access denied (IDOR probes), expired/revoked tokens rejected,
   reset tokens single-use, rate limits trip. Run the full suite.

## Rules

- Secrets and keys come from environment config, never committed.
- Error messages must not reveal whether an email or account exists.
- If a maintained auth library or service in the stack covers a need, use it
  instead of hand-building; note any deviation and why.

Audit the dependencies of this repository. The goal: identify security risks,
license concerns, and stale packages, then provide a prioritized fix plan.

## Steps

1. **Run the vulnerability scanner** - Use the repo's native tooling:
   `npm audit`, `pip-audit`, `cargo audit`, `bundler-audit`, `govulncheck`,
   or `gh extension security`. Capture the full output. If no scanner is
   configured, set up the appropriate one for the stack.
2. **Check licenses** - Identify all dependency licenses using the repo's
   package manager or a license checker. Flag any copyleft licenses (GPL,
   AGPL) or licenses incompatible with the project's own license. List
   permissive licenses (MIT, BSD, Apache) as clean.
3. **Assess staleness** - For each direct dependency, check: when it was
   last published, how many versions behind it is, and whether it has been
   deprecated or archived. Flag packages with no release in over a year.
4. **Classify risk** - For each finding, assess:
   - **Critical/High** - Known exploitable vulnerability, active in the
     dependency tree
   - **Medium** - Vulnerability with mitigating factors or transitive
     dependency
   - **Low** - Outdated but no known vulnerability, or dev-only dependency
   - **License** - Incompatible license that may have legal implications
5. **Provide fix recommendations** - For each finding: the recommended
   version to upgrade to, whether the upgrade is semver-compatible (safe) or
   a major version (requires migration), and any breaking changes to watch
   for. Group fixes by effort level: drop-in replacements first, then minor
   migrations, then major rewrites.
6. **Verify fixes** - After applying recommended upgrades, re-run the
   vulnerability scanner and test suite to confirm the fixes work without
   regressions.

## Rules

- Never upgrade dependencies blindly without checking the changelog for
  breaking changes.
- Never ignore a critical vulnerability because "it's probably not
  exploitable in our context" - document the risk assessment instead.
- Never add new dependencies to fix audit findings without checking if the
  existing dependency has a safe version.
- If a dependency is abandoned with no maintained fork, flag it for
  replacement rather than continuing to use it.

Design and run load tests for `[endpoint / service / workflow]` in this
repository. The goal: measurable performance under load with clear pass/fail
thresholds, not just "it didn't crash."

## Steps

1. **Identify what to test** - Read the code to find the critical paths that
   need load testing: high-traffic endpoints, resource-intensive operations,
   database-heavy queries, or integrations with external services. Prioritize
   by business impact and expected traffic.
2. **Define realistic scenarios** - Model real user behavior: the mix of
   requests (read vs write), think time between requests, authentication
   patterns, and data volume. Use realistic payloads, not minimal test data.
   Consider both normal load and peak load scenarios.
3. **Choose the tool** - Use the repo's existing load testing tooling if it
   exists (k6, locust, Apache Bench, wrk, artillery). If none exists, pick
   the standard tool for the stack and set it up.
4. **Set thresholds** - Define measurable pass/fail criteria before running:
   - Response time: p50, p95, p99 latencies under load
   - Throughput: requests per second sustained
   - Error rate: maximum acceptable percentage (e.g. < 0.1%)
   - Resource usage: CPU, memory, connection pool limits
5. **Run the tests** - Execute against a staging or local environment that
   mirrors production. Run warm-up iterations first. Capture and save the
   full results with timestamps.
6. **Analyze and report** - Compare results against thresholds. Identify
   bottlenecks: database queries, connection pool exhaustion, memory leaks,
   or external service latency. Provide before/after numbers if making
   optimization changes.

## Rules

- Never run load tests against production without explicit approval and a
  maintenance window.
- Never report results without thresholds - "it handled 1000 rps" means
  nothing without knowing if that's enough.
- Never use toy data volumes that don't represent real usage patterns.
- If the test environment differs significantly from production, document
  the differences and how they affect the results.

Find and fix the memory leak in `[service or component]`. Work from
measurements, never from suspicion: a process that "seems to grow" is not
evidence. Establish the baseline curve, reproduce steady growth, isolate the
retainer, fix it minimally, and prove the curve flattens.

## Steps

1. **Take the baseline** - Determine the repo's own memory tooling and how the
   service is run (entry command, config, test harness). Measure RSS and, where
   available, the heap across a fixed window of the service's normal work. Record
   the numbers so the hunting has a before to compare against.
2. **Reproduce the growth** - Drive a repeatable scenario (same request, same
   operation, looped) and show the allocation curve rising with the loop count.
   A leak reproduces deterministically: the scenario you cannot grow is a
   symptom you have not isolated yet, not a non-issue.
3. **Get an allocation snapshot** - Use the stack's profiler or heap snapshot
   tooling (heap snapshot / sampling profiler / native tooling, whichever the
   repo already uses). Diff two snapshots taken one interval apart to see which
   objects and which root hold them.
4. **Name the retainer** - Identify the shortest ownership chain that keeps
   memory alive. Common suspects to check with evidence: an unbounded cache or
   public static collection, event listeners or subscriptions never removed,
   timers or intervals not cleared, closures holding large objects, pooled or
   reused objects accumulating fields, streams or connections not closed.
5. **Fix the smallest thing** - Change the retainer, not the surroundings: bound
   or evict the cache, remove the listener on unmount, clear the interval, close
   the stream. Prefer the boring fix that removes the reference over a clever
   rewrite.
6. **Verify by re-running the same scenario** - Run the exact loop from step 2
   for at least as long as before and show the curve is flat (or bounded) where
   it used to climb. Report the before and after numbers; a claim that it is
   fixed without the curve is not a fix.

## Rules

- Never patch based on an anecdote. Every change must be tied to a measured
  retainer from a snapshot, not a guess.
- One fix per investigation until the curve is flat; do not stack unrelated
  memory changes in the same change.
- Never disable a feature to hide the leak, and never add a periodic GC or pool
  flush as the "fix" without proving the root cause.
- No unrelated edits: this change only touches the leak path and its test.

## Verification

Paste the before and after memory curves (same scenario, same duration) with the
command that produced each. Show the retainer and ownership chain from the
diffed snapshots, and quote the line that holds the reference, with the fix on
top of it. Run the repo's test suite and show it passes.

Optimize the performance of `[feature / endpoint / function / hot path]` in
this repository. The rule: **measure first, prove every change**.

## Method

1. **Establish a baseline** - Find or build a way to measure the current
   behavior: a benchmark, profiling run, request latency, or load test. Use
   the repo's existing tooling where possible (pytest-benchmark, k6, flame
   graphs, `top`/`time`, browser DevTools). Record the baseline number.
2. **Find the real bottleneck** - Profile and locate the actual hotspot. It
   is almost never where you guess. Read the code path and identify what is
   actually slow: N+1 queries, repeated work in a loop, blocking I/O in a hot
   path, naive data structures, excessive allocations, or a bad algorithm.
   Cite the evidence (profile output, file:line).
3. **Fix the smallest thing** - Apply the minimal change that removes the
   bottleneck while preserving behavior. Prefer the boring fix (an index, a
   cached value, an early exit) over clever hacks. Follow repo conventions.
4. **Prove it** - Re-run the same measurement. Report before/after numbers.
   If the change doesn't measurably help, revert it and say so - don't keep a
   "probably faster" change.
5. **Verify correctness** - Run the test suite and the repo's checks. A fast
   but broken change is a failure.
6. **Document** - Note the trade-off in the changelog or a comment only where
   the repo expects it (e.g. a behavior change or a config knob).

## Rules

- No premature optimization. If nothing is measurably slow, say so and stop.
- Never sacrifice clarity, correctness, or security for a marginal gain.
- Never micro-optimize without data (avoid "this loop could be a list
  comprehension" without evidence it matters).
- If the win comes with a trade-off (memory, complexity, portability), state
  it plainly.

Audit this repository for hardcoded secrets and set up proper secret
management. The goal: no secrets in code, no secrets in git history, and a
clear pattern for handling secrets going forward.

## Steps

1. **Scan for secrets in code** - Search the entire codebase for hardcoded
   API keys, tokens, passwords, connection strings, private keys, and any
   other sensitive values. Check: source files, config files, env files
   committed to the repo, Dockerfiles, CI configs, and test fixtures. Use
   pattern matching for common secret formats (AWS keys, JWT tokens,
   database URLs with passwords).
2. **Scan git history** - Check past commits for secrets that have been
   removed from the current code but remain in git history. Use `git log -p`
   with grep patterns, or a dedicated tool like `trufflehog` or `gitleaks`
   if available.
3. **Classify findings** - Categorize each finding by severity:
   - **Critical** - Active credentials that could grant access (API keys,
     database passwords, private keys)
   - **High** - Secrets in git history that need rotation
   - **Medium** - Placeholder or example secrets that should still be
     removed for hygiene
   - **Low** - Non-sensitive values that look like secrets but aren't
4. **Remediate** - For each finding:
   - Move the secret to an environment variable or secrets manager
   - Replace the hardcoded value with a reference to the env var
   - Update the code to read from the new source
   - Add the secret name to `.env.example` (without the value) so new
     contributors know what's needed
5. **Set up the pattern** - Create or update `.env.example` with all
   required secrets (names only, no values). Update `.gitignore` to exclude
   `.env` files. Document the secret setup process in the README.
6. **Verify** - Confirm no secrets remain in source code. If git history
   contains secrets, document the rotation plan (the actual rotation must
   happen out-of-band).

## Rules

- Never commit actual secret values as examples - use placeholder strings
  like `your-api-key-here`.
- Never log secrets or include them in error messages.
- If secrets are found in git history, do not just remove them from HEAD -
  they need rotation and history rewriting or acknowledgment.
- If the project uses a secrets manager (Vault, AWS Secrets Manager, etc.),
  integrate with it rather than introducing a new solution.

Audit this repository for security vulnerabilities. Be rigorous and honest:
report real issues with evidence, and skip anything you can't verify. Your
findings are what the team will act on, so accuracy matters more than volume.

## Scope to cover

1. **Injection & input handling** - SQL/NoSQL injection, shell injection,
   command execution, path traversal, template injection, unsafe deserialization.
2. **Authentication & authorization** - broken auth, default/weak credentials,
   missing authorization checks, privilege escalation, session handling.
3. **Data exposure** - secrets and API keys committed in the repo or in git
   history, sensitive data in logs, responses exposing internal details,
   insecure storage/transmission (HTTP, no TLS).
4. **Web-specific** - the OWASP Top 10 as it applies to the code: XSS, CSRF,
   SSRF, open redirects, insecure headers, IDOR.
5. **Dependencies** - known-vulnerable packages (run the repo's dependency
   scanner if configured, e.g. `npm audit`, `pip-audit`, `gh security`).
6. **Configuration** - over-permissive permissions, debug mode enabled,
   unsafe defaults, missing rate limiting/input validation.

## Method

- Read the actual code; trace untrusted input from entry point to sink. Do not
  claim a vulnerability without showing the path.
- Verify each finding yourself (run commands, check configs, read docs) before
  reporting it. For secrets in history, confirm with `git log -p` and
  `git rev-list --all`.
- Assess real-world exploitability and severity (Critical/High/Medium/Low),
  not just theoretical risk.

## Output

A findings report, each item with: the vulnerability, the evidence (file:line
and the code path), severity, real-world impact, and a concrete fix. End with
a prioritized fix list and any quick wins. Be clear about what was checked and
found clean.

## Rules

- Do **not** change code, push fixes, or rotate secrets without explicit
  approval - report first.
- Never redact or dismiss a real finding because it's awkward. Report it
  plainly.
- If something looks vulnerable but you can't confirm the path, mark it as
  "needs confirmation" rather than a confirmed finding.

Threat-model the specified feature or system in this repository. Produce a
ranked list of realistic threats with mitigations - not a generic checklist.

## Steps

1. **Diagram the trust boundaries** - Components, data flows, and every
   boundary where an attacker can inject influence (user input, third-party
   APIs, webhooks, file uploads, admin surfaces). Apply STRIDE per boundary:
   Spoofing, Tampering, Repudiation, Information disclosure, Denial of
   service, Elevation of privilege.
2. **Enumerate threats concretely** - For each element: what could an
   attacker with that vantage point do? Name the actor (anonymous user,
   authenticated peer, compromised dependency, insider) and the asset at
   risk. Vague threats ("input might be malicious") are rejected; specific
   ones ("the webhook endpoint accepts unsigned payloads, so anyone can forge
   events") are the goal.
3. **Rate realistically** - Impact times likelihood with a one-line
   justification each. Consider exploitability, not just severity if
   exploited.
4. **Mitigate in order** - For each accepted threat: the control (validation,
   signature verification, authz check, rate limit, encryption), where it
   lives in the code, and how to verify it works. Mark residual risk after
   mitigation.
5. **Turn top findings into work** - Concrete tasks and tests: the negative
   test that proves the control rejects the attack, and the regression that
   keeps it fixed.

## Output

A threat model table (threat, actor, asset, STRIDE category, risk,
mitigation, verification) plus the top three mitigations to implement first.

## Rules

- Ground every threat in the actual architecture - read the code, routes, and
  config first; flag assumptions explicitly.
- Do not implement mitigations unprompted; propose them.
- A security control without a verification step does not count as mitigated.

Write an ADR for a decision made (or being made) in this repository. The goal
is a short, factual record of what was decided, why, and what alternatives
were rejected - readable in two minutes by someone with no context.

## Steps

1. **Identify the decision** - Pin down exactly what was decided and when.
   Read the relevant code, config, and docs first so the ADR matches reality,
   not intention.
2. **Gather context** - What problem forced this decision? What constraints
   applied (team, deadline, stack, cost)? Cite evidence: issues, PRs, code.
3. **List considered options** - At least two real alternatives plus the
   chosen one. For each: one-line summary, pros, cons.
4. **Justify the choice** - Why this option won given the context. Be
   specific: "Postgres because we need transactions and already run it"
   beats "it's industry standard".
5. **Record consequences** - What becomes easier, what becomes harder, what
   new obligations follow (migrations, runbooks, license costs).
6. **Number and file it** - Follow the repo's existing ADR convention if
   there is one (`docs/adr/`, `adr/`); otherwise propose `docs/adr/NNNN-title.md`
   with the next free number.

## Output

One ADR file with this structure: Title, Status (proposed/accepted/
superseded), Context, Decision, Options considered, Consequences. Keep it
under ~100 lines.

## Rules

- Describe the decision as made, not as you wish it had been made.
- No rewriting history: if a decision looks wrong today, note it as a
  candidate for a superseding ADR instead of editing the old one.
- Every claim about the codebase must be verified against the actual code.

Design and implement caching for this application where measurement shows it
helps. Cache only what is measurably expensive and safely cacheable; wrong
caching is worse than no caching.

## Steps

1. **Measure first** - Identify the expensive operations worth caching (slow
   queries, hot endpoints, computed results) with numbers: latency, call
   frequency, cost per call. No measurement, no cache.
2. **Classify the data** - For each candidate: how fresh must it be, who can
   write it, is it user-specific or shared, what staleness is tolerable?
   This determines TTL, key design, and invalidation strategy.
3. **Choose layers deliberately** - Pick the cheapest layer that works: HTTP
   cache headers, in-process memoization, distributed cache (Redis and
   friends), CDN, materialized views. Justify each layer against a simpler
   alternative.
4. **Design keys and invalidation before writing code** - Keys must include
   every input that changes the result. Decide: TTL-only, explicit eviction
   on write, versioned keys, or event-driven invalidation - and state the
   stale window users could see.
5. **Implement with guardrails** - Bounded memory/size limits, stampede
   protection for hot keys (single-flight/locking), graceful behavior when
   the cache is down (fall through to source), and metrics: hit rate,
   latency, evictions.
6. **Verify** - Show before/after latency on the target path, prove
   invalidation works (write then read returns the new value within the
   promised window), and load-test the hot path.

## Rules

- Never cache per-user data under a shared key, and never cache responses
  that vary by session or headers as if they were public.
- If you cannot define how and when an entry becomes invalid, do not add the
  cache yet.
- Report the stale-data window explicitly so its owner can accept it.

Debug this concurrency problem (race condition, deadlock, flaky parallel
test, or async ordering bug). Concurrency bugs are proven, not guessed: you
must be able to explain the exact interleaving that causes the failure.

## Steps

1. **Reproduce reliably** - Find or build a reproduction that fails more
   often than not: stress loops, reduced delays, forced scheduling, raised
   thread/task counts. A repro you cannot trigger on demand cannot confirm a
   fix.
2. **Map shared state** - Identify exactly which data is shared across
   threads/tasks/processes, which accesses are reads vs writes, and what
   synchronization (locks, atomics, channels, transactions) currently guards
   them. Write the map down before theorizing.
3. **Explain the interleaving** - State the precise sequence of events that
   produces the bug: who writes what, who reads stale state, who observes a
   half-done update. If you cannot narrate the interleaving, keep digging.
4. **Pick the minimal fix** - Prefer the smallest correct mechanism: shrink
   critical sections, use the language's appropriate primitive (atomic,
   mutex, message passing, idempotent retry), or restructure to remove shared
   mutable state entirely. Never add a second lock where one lock held
   correctly suffices, and never "fix" with sleeps or timeouts.
5. **Prove it** - Run the stress repro many times pre-fix (show failures) and
   post-fix (show clean runs). Enable detectors if available (ThreadSanitizer,
   `-race`, deterministic-scheduling test tools). Run the full suite.
6. **Check neighbors** - Look for the same pattern elsewhere in the codebase
   and report locations; don't fix them silently.

## Rules

- Never claim fixed without demonstrating the interleaving is impossible or
  handled, backed by repeated clean runs.
- Sleep-based "fixes" are not fixes - reject them explicitly.
- Note deadlock potential of any new locking (lock ordering, reentrancy).

Design the specified system for this project. Produce an architecture a team
could start building tomorrow - concrete, justified, and honest about
tradeoffs. Do not hand-wave scale or skip the boring parts (auth, failure,
data growth).

## Steps

1. **Clarify requirements** - Restate functional requirements, then pin down
   non-functional ones: expected users, read/write ratio, data volume now
   and in a year, latency targets, availability target, consistency needs.
   If a number is unknown, state your assumption explicitly and size for it.
2. **Constrain before creating** - List hard constraints: team size, budget,
   managed vs self-hosted, existing stack, compliance. A design that ignores
   constraints is a wish list, not a design.
3. **Sketch the high-level architecture** - Major components, their
   responsibilities, and how data flows between them. One diagram (mermaid)
   plus prose - never diagram alone.
4. **Design the data layer** - Schema/model, storage engine choice with
   justification, access patterns, indexing, retention.
5. **Address cross-cutting concerns** - AuthN/AuthZ, input validation,
   secrets handling, observability (logs/metrics/traces), rate limiting, and
   caching only where it earns its complexity.
6. **Plan for failure** - What breaks first under load? What happens when
   each dependency is down? Define degradation behavior and recovery for
   each.
7. **State tradeoffs** - For every major choice, name the alternative you
   rejected and why. Include a "what would force us to redesign" threshold.
8. **Phase the build** - An MVP slice that works end-to-end, then increments.
   Call out the riskiest unknowns to validate first.

## Output

A design doc: requirements and assumptions, architecture diagram, component
breakdown, data model, API surface sketch, failure modes, tradeoff table,
and a phased delivery plan.

## Rules

- No component without a reason it exists; no technology without a why-now
  justification versus simpler options.
- Numbers beat adjectives: "p95 under 200ms", not "fast".
- Flag every assumption so readers can challenge it; never present guesses as
  decisions.

Inventory the technical debt in this repository and produce a triaged,
prioritized paydown plan. Debt means anything that makes change slower or
riskier than it should be: tangled modules, missing tests on critical paths,
outdated dependencies, drift between docs and behavior, TODO clusters.

## Steps

1. **Survey** - Scan the repo systematically: module coupling and size
   hotspots (largest files/functions), test coverage gaps on critical paths,
   dependency staleness, TODO/FIXME/HACK density, config sprawl, doc/code
   drift.
2. **Verify impact** - For each candidate item, confirm it actually hurts:
   find evidence (bug reports touching that area, slow CI stages, repeated
   workarounds). Discard items with no observable cost.
3. **Quantify crudely but honestly** - Estimate effort (S/M/L) and the risk
   of leaving it (what breaks, what it blocks). Prefer measured signals (test
   counts, bundle size, build time) over adjectives.
4. **Triage** - Sort into: fix now (blocks current work or risks incidents),
   schedule (real cost, not urgent), accept (cost exceeds payoff - document
   why), delete (dead code/config - removing beats refactoring).
5. **Plan** - For "fix now" and "schedule" items: a concrete first step, how
   to do it incrementally without a big-bang rewrite, and how to verify the
   improvement (metric before/after).

## Output

A table: item, evidence, effort, risk of inaction, verdict, first step. Then
the top three actions you would take this week and why.

## Rules

- No drive-by refactoring: this task produces a plan, not diffs, unless asked.
- Do not pad the list - ten real debts beat forty speculative ones.
- Dead code is debt too: recommend deletion where behavior isn't referenced.

Find the real bugs in this repository. Sweep the codebase across the factors
below, read the actual code, and produce a clear, priority-ordered list of
confirmed bugs. Accuracy beats volume: only report what you can verify with
evidence. Do not change any code - this is a read-only hunt.

## Define the scope first

Before reading, state:

1. **Target** - Whole repo, or a specific module/directory/SHA range? If the
   repo is large, propose the highest-value slice (core logic, recently
   changed code) and say so.
2. **Factors to prioritize** - Which bug families matter most for this
   codebase (the stack and its riskiest areas, e.g. a React frontend vs a
   payment CLI vs a data pipeline)? Weight your search accordingly.
3. **Out of scope** - Security-only findings and style nits are checked only
   where they cause a real correctness bug; deep security and performance
   audits have their own prompts.

## Factors to examine

1. **Logic & control flow** - Off-by-one errors, inverted or missing
   conditions, dead/unreachable branches, incorrect operators, wrong
   early-returns, missing edge cases (empty input, zero, null, max values).
2. **Data handling** - Off-by-one and boundary issues, type/encoding
   mismatches, integer overflow, truncation, units and timezone mistakes,
   NaN/Infinity, silent data loss.
3. **State & concurrency** - Shared mutable state, race conditions, stale
   closures/caches, resource leaks not closed on error paths, reentrancy,
   unintentional shared references (alias bugs).
4. **Error handling** - Swallowed exceptions, unhandled error paths, wrong
   error recovery, partial-failure inconsistency (some steps done, others
   not), missing rollback/cleanup.
5. **API & integration** - Wrong argument order, mismatched types, broken
   contracts between callers and callees, incorrect external calls,
   off-by-one pagination/offsets, encoding/locale differences.
6. **Configuration & environment** - Wrong defaults, env vars required but
   unchecked, mismatched toggles, incorrect config values for the
   environment.
7. **Null & reference safety** - Null/undefined dereferences, nullable
   values treated as non-null, missing existence checks, stale object
   references.

## Method

1. **Read before concluding** - No claim without reading the code path that
   proves it. Trace inputs from entry point through the buggy line.
2. **Verify each candidate** - For every suspected bug, confirm it is real:
   check the surrounding code, types, callers, and expected behavior. Reject
   anything you cannot prove. A bug you cannot demonstrate is not reported.
3. **Trace the impact** - Show how the bug manifests for a user or system:
   what input triggers it and what wrong thing happens.
4. **Check whether tests cover it** - Note if an existing test should have
   caught it but doesn't, or if one is missing. This shows confidence.
5. **Confirm, don't assume** - Where possible run the repo's tooling (tests,
   linters, type checker) to support a finding, but only report the bug when
   reasoning and/or an executable check confirms it.

## Output

A prioritized bug report. For each confirmed bug:

- **Severity** - Critical (data loss/corruption, crash on a common path,
  wrong money/security result) / High / Medium / Low.
- **The bug** - One clear sentence describing the incorrect behavior.
- **Evidence** - `file:line`, the triggering input/path, and why it is wrong.
- **Impact** - What breaks in practice and who hits it.
- **Fix** - A one-to-three line concrete fix (do not apply it).

Then end with:

- A **summary table**: ID | severity | file:line | one-line bug.
- A **things checked and clean** note listing factors you swept that surfaced
  no confirmed bugs.
- **Needs confirmation** - anything suspicious you could not fully prove,
  clearly separated from confirmed findings.

## Rules

- Read-only: do not modify, fix, or refactor code. Report first.
- Never pad the list. If you found 3 real bugs, report 3 - not 20 that you
  could not verify.
- Distinguish confirmed bugs from "needs confirmation" and from style
  preferences.
- If a suspected bug is guarded by an unclear invariant, mark it "needs
  confirmation" and say what would resolve it.
- Be concise and concrete. No filler like "this code could be improved".

Find the real bugs in this repository and document them. Sweep the codebase
across the factors below, read the actual code, and produce a clear,
priority-ordered list of confirmed bugs. Then record every finding in the
repo's documentation so the list survives as a durable artifact. Accuracy
beats volume: only report what you can verify with evidence. Do not change
any code - fix nothing, but do leave the documentation behind.

## Define the scope first

Before reading, state:

1. **Target** - Whole repo, or a specific module/directory/SHA range? If the
   repo is large, propose the highest-value slice (core logic, recently
   changed code) and say so.
2. **Factors to prioritize** - Which bug families matter most for this
   codebase (the stack and its riskiest areas, e.g. a React frontend vs a
   payment CLI vs a data pipeline)? Weight your search accordingly.
3. **Documentation destination** - Where the findings should be recorded: a
   dedicated bug ledger (`BUGS.md` at the repo root), a section in the README,
   a `docs/` page, or somewhere the repo already keeps known issues. Propose
   what fits this repo and say so.

## Factors to examine

1. **Logic & control flow** - Off-by-one errors, inverted or missing
   conditions, dead/unreachable branches, incorrect operators, wrong
   early-returns, missing edge cases (empty input, zero, null, max values).
2. **Data handling** - Off-by-one and boundary issues, type/encoding
   mismatches, integer overflow, truncation, units and timezone mistakes,
   NaN/Infinity, silent data loss.
3. **State & concurrency** - Shared mutable state, race conditions, stale
   closures/caches, resource leaks not closed on error paths, reentrancy,
   unintentional shared references (alias bugs).
4. **Error handling** - Swallowed exceptions, unhandled error paths, wrong
   error recovery, partial-failure inconsistency (some steps done, others
   not), missing rollback/cleanup.
5. **API & integration** - Wrong argument order, mismatched types, broken
   contracts between callers and callees, incorrect external calls,
   off-by-one pagination/offsets, encoding/locale differences.
6. **Configuration & environment** - Wrong defaults, env vars required but
   unchecked, mismatched toggles, incorrect config values for the
   environment.
7. **Null & reference safety** - Null/undefined dereferences, nullable
   values treated as non-null, missing existence checks, stale object
   references.

## Method

1. **Read before concluding** - No claim without reading the code path that
   proves it. Trace inputs from entry point through the buggy line.
2. **Verify each candidate** - For every suspected bug, confirm it is real:
   check the surrounding code, types, callers, and expected behavior. Reject
   anything you cannot prove. A bug you cannot demonstrate is not reported.
3. **Trace the impact** - Show how the bug manifests for a user or system:
   what input triggers it and what wrong thing happens.
4. **Check whether tests cover it** - Note if an existing test should have
   caught it but doesn't, or if one is missing. This shows confidence.
5. **Confirm, don't assume** - Where possible run the repo's tooling (tests,
   linters, type checker) to support a finding, but only report the bug when
   reasoning and/or an executable check confirms it.

## Output

### Part 1 - The bug report

A prioritized bug report. For each confirmed bug:

- **Severity** - Critical (data loss/corruption, crash on a common path,
  wrong money/security result) / High / Medium / Low.
- **The bug** - One clear sentence describing the incorrect behavior.
- **Evidence** - `file:line`, the triggering input/path, and why it is wrong.
- **Impact** - What breaks in practice and who hits it.
- **Fix** - A one-to-three line concrete fix (do not apply it).
- **Docs updated** - What you documented for it and where.

Then end the report with:

- A **summary table**: ID | severity | file:line | one-line bug.
- A **things checked and clean** note listing factors you swept that surfaced
  no confirmed bugs.
- **Needs confirmation** - anything suspicious you could not fully prove,
  clearly separated from confirmed findings.

### Part 2 - The documentation

1. **Create the bug ledger** - If none exists, create a `BUGS.md` (or the
   agreed destination) at the repo root containing: a one-line purpose, the
   date and scope of this sweep, and a table/list of every confirmed bug with
   ID, severity, `file:line`, status `open`, one-line description, and where
   it was reproduced. Mark each entry so it can be closed later, e.g. a
   status column to flip when fixed.
2. **Link the ledger from the README** - Add a short "Known issues / bug
   ledger" pointer in the README (or the closest existing docs) so the ledger
   is discoverable. Follow the repo's existing doc conventions - heading
   style, table format, tone.
3. **Record unconfirmed suspicions** - Put "needs confirmation" items in the
   ledger under a clearly separated section, each with what would resolve it.
4. **Leave the code alone** - Update docs only. Do not fix, refactor, or
   annotate source files unless fixing a doc comment that is wrong
   specifically because it documents the bug's behavior as correct.

## Rules

- Update documentation, never code. Report-and-document first; fixing is a
  separate follow-up.
- Never pad the list. If you found 3 real bugs, report 3 - not 20 that you
  could not verify.
- Distinguish confirmed bugs from "needs confirmation" and from style
  preferences.
- If a suspected bug is guarded by an unclear invariant, mark it "needs
  confirmation" and say what would resolve it.
- Documentation must match the repo's existing style, and every claim in it
  must trace to a verified finding - no filler like "this code could be
  improved".
- If the repo already has a bug ledger or known-issues doc, update it, do not
  create a second one.

Test this system's resilience by injecting failures. The question is never
"does it work?" but "what happens when X is slow, down, or full?" - and the
answer must come from experiments, not confidence.

## Steps

1. **Build the failure map** - List external dependencies and failure modes:
   downstream APIs (timeout, 500s, slow responses), the database (connection
   exhaustion, lock timeouts), queues (backlog, poison messages),
   disk/network (full, partitioned), clock skew. Note current handling for
   each.
2. **Form hypotheses** - For each dependency, predict the behavior when it
   fails: what does the user see? how often does it retry? does the process
   crash, hang, or degrade? Write predictions down before testing.
3. **Inject safely** - Experiment in a staging-like environment first; use
   the least invasive tool available (fault-injection proxies, network
   shaping, kill switches, resource limits). Production experiments only with
   explicit approval, capped blast radius, and an abort plan.
4. **Observe honestly** - Compare observed behavior to hypotheses. Classic
   findings: missing timeouts (hangs forever), retry storms amplifying
   outages, cascading failure from connection pool exhaustion, silent data
   loss, alerting that never fires.
5. **Fix what broke** - Implement the minimal resilience fixes: explicit
   timeouts everywhere, bounded retries with backoff and jitter, circuit
   breakers on repeat offenders, bulkheads around shared resources, graceful
   degradation paths (cache fallback, queue-and-resume).
6. **Re-run and codify** - Repeat injections post-fix and show the
   difference. Turn surviving experiments into automated tests or CI jobs
   where practical, and document the system's known failure behaviors.

## Rules

- Never run destructive experiments against production data without explicit
  sign-off and a rollback plan.
- A timeout default of "none/infinite" is a defect - flag every one found.
- Report what was tested and what wasn't; untested resilience is unknown, not
  proven.

Find the untested and under-tested parts of this repository and close the gaps
with meaningful tests. The goal is risk reduction, not a higher coverage
number.

## Steps

1. **Measure** - Run the repo's coverage tool (find it in `pyproject.toml`,
   `package.json`, `Makefile`, or CI config) and note the current coverage and
   where the red lines are.
2. **Prioritize by risk, not lines** - Rank uncovered code by how much damage
   a regression would cause: core logic, error handling, security-sensitive
   code, public APIs, and code most likely to change rank highest. Ignore
   trivial gaps (plain getters, dead code, generated files).
3. **Explain the gaps** - For each gap you target, state why it's risky and
   what behavior is unprotected. Don't write tests for code you haven't
   reasoned about.
4. **Write the tests** - Follow the repo's test conventions. Assert real
   behavior, including the failure and edge-case paths that are usually the
   uncovered ones (timeouts, bad input, empty results, partial failures).
5. **Verify** - Run the suite and the coverage report again. Report the
   before/after delta and, more importantly, what risk you removed.

## Rules

- Never add a test whose only purpose is to touch a line (e.g. calling a
  getter and ignoring the result). Coverage is a byproduct, not the target.
- Don't write tests for dead or unreachable code - flag it for removal instead.
- Don't weaken existing assertions to improve coverage.
- If a piece of code is painful to test, say so and suggest a small
  refactor rather than fighting it with a contrived test.

Set up contract testing between this service and its consumers or providers.
Goal: each side verifies against a shared contract in CI, so breaking changes
fail builds instead of production integrations.

## Steps

1. **Map the interfaces** - List the HTTP/message interfaces this service
   provides and consumes, with their counterpart services. Pick the highest-
   churn or most critical interface to start with - one contract, end to end.
2. **Choose tooling that fits the stack** - Use an established framework
   (Pact and equivalents) matching the languages involved; prefer a pattern
   the repo already uses if one exists.
3. **Write consumer expectations as contracts** - Capture what the consumer
   actually calls: request to expected response shape and status, including
   error cases and empty collections. Contracts encode usage, not the
   provider's full schema.
4. **Verify on the provider side** - Replay contracts against the real
   provider (state set up via hooks/fixtures). Every mismatch is a finding:
   either a real break or an outdated expectation - resolve it explicitly.
5. **Wire the workflow** - Publish contracts on consumer CI; provider CI
   fetches and verifies them; gate merges on verification (broker or
   repo-based flow). Document the flow in CONTRIBUTING or the README.
6. **Grow gradually** - Add contracts interface-by-interface for critical
   paths. Delete contracts when the interaction dies; stale contracts erode
   trust in the whole suite.

## Rules

- A contract nobody verifies in CI is documentation, not a test - wire it or
  drop it.
- Never loosen a contract just to make a failing build green; change the code
  or consciously version/bump the contract with the consumer's agreement.
- Contract tests complement, not replace, integration smoke tests.

Scaffold end-to-end or integration tests for `[feature / workflow / route]`.
The goal: tests that verify real user flows work correctly, with realistic
fixtures and CI-ready setup.

## Steps

1. **Understand the flow** - Read the code for the user journey you are
   testing: entry point, all code paths, side effects (database writes, API
   calls, file system changes), and the expected final state. Trace the full
   path, not just the happy case.
2. **Identify what to test** - Prioritize flows that are high-risk or
   high-traffic: critical user journeys, complex multi-step processes, integrations
   with external services. Do not test things better covered by unit tests
   (pure logic, utilities).
3. **Set up the test environment** - Use the repo's existing test framework
   and fixtures. Set up the database state, mock external services where the
   repo uses test doubles, and configure any required environment variables.
   Follow the repo's conventions for test setup and teardown.
4. **Write realistic scenarios** - Test the full flow as a user would
   experience it: navigate to the page, fill the form, submit, verify the
   result. Include realistic data, not placeholder strings. Cover the happy
   path and the primary error paths.
5. **Add assertions at boundaries** - Assert on observable outcomes: the
   response status, the database state after the operation, the UI content
   rendered. Avoid asserting on implementation details (internal function
   calls, CSS class names).
6. **Verify the tests run** - Execute the test suite. Confirm the new tests
   pass and existing tests are not broken. Check that the tests are
   deterministic (no flakiness from timing, random data, or shared state).

## Rules

- Never write tests that depend on external services without mocks or
  testcontainers.
- Never skip teardown - each test must leave the environment clean for the
  next one.
- If the test requires more than 3 setup steps, extract them into shared
  helpers or fixtures.
- Tests that pass sometimes and fail sometimes are worse than no tests - fix
  flakiness before merging.

Run mutation testing on `[module / file / test suite]` in this repository.
The goal: find tests that pass even when the code is broken - these are the
gaps where coverage lies.

## Steps

1. **Check the tooling** - Determine what mutation testing framework fits the
   repo's stack (Stryker for JS/TS, mutmut for Python, pitest for Java,
   cargo-mutants for Rust). Install and configure it following the repo's
   conventions. If none exists, set up the standard tool for the language.
2. **Run the baseline** - Execute mutation testing on the target module and
   record the baseline mutation score (killed / total mutations). Note which
   files and test files are covered.
3. **Analyze surviving mutants** - Examine every mutant that survived (tests
   passed despite the mutation). Categorize them:
   - **Trivially killed** - the mutant changed something the tests already
     cover but the assertion is too weak to catch it.
   - **Actually survived** - the mutant changed behavior the tests do not
     verify at all.
   - **Equivalent mutants** - the mutation is semantically identical to the
     original code (these can be ignored).
4. **Strengthen the tests** - For each meaningful surviving mutant, add or
   fix the test that should catch it. Strengthen assertions, add edge case
   tests, or add new test cases for untested code paths.
5. **Re-run and verify** - Run mutation testing again. The mutation score
   should improve. Confirm no existing tests broke from the changes.
6. **Report** - Summarize: starting score, number of mutants analyzed, number
   killed, equivalent mutants excluded, and final score. List the specific
   gaps that were fixed.

## Rules

- Never skip the equivalent mutant analysis - some mutations are genuinely
  unkillable and should not count against the score.
- Never add tests just to kill mutants if the mutant represents a change that
  doesn't matter in practice. Focus on meaningful behavior.
- If the mutation testing tool does not support the repo's language or
  framework, say so clearly instead of forcing an incompatible tool.
- Mutation testing is a complement to code coverage, not a replacement. Use
  both.

Implement `[feature/task]` using strict test-driven development in this
repository. The discipline is the point - follow the cycle exactly.

## The cycle

1. **RED** - Write one failing test for the smallest useful piece of behavior.
   Run it and confirm it fails for the right reason (it fails because the
   behavior doesn't exist, not because of an error in the test itself).
2. **GREEN** - Write the minimum code to make that test pass. No extra
   features, no cleanup yet, no "while I'm here" changes.
3. **REFACTOR** - Clean up the code you just wrote while keeping the tests
   green. Remove duplication, improve naming, follow repo conventions.

Repeat until the feature is complete. Do not proceed to the next test while
any test is failing.

## Ground rules

- Design the tests from the **outside in**: write the test the way a caller
  would use the code. Keep the tests focused on behavior and interface.
- Each test should cover one behavior. If a test is getting big, split it.
- Commit at logical points (a green commit per cycle is fine) with the repo's
  commit convention.
- At the end: run the full suite plus lint/format/type checks with the repo's
  tooling and confirm everything is green.

## Rules

- Never write production code before the failing test exists for it.
- Never delete, disable, or weaken a failing test to go green - the code
  must change.
- If a test is genuinely wrong (the requirement changed), update it and say
  so explicitly - don't quietly change tests to match implementation.

Write tests for `[function/module/feature]` in this repository. The goal is
tests that catch regressions and document behavior - not tests that pad the
coverage number.

## What good looks like

1. **Read the code first** - Understand the inputs, outputs, side effects,
   error paths, and the contract callers rely on before writing anything.
2. **Test behavior, not implementation** - Assert what the code does
   (return values, state changes, errors raised, side effects), not how it
   does it. Don't restate the code path in test assertions.
3. **Cover the meaningful cases** - The happy path, key edge cases (empty
   input, boundary values, missing data, invalid input), and error handling.
   Prioritize the cases most likely to break in the future.
4. **Match the repo's style** - Use the existing test framework, naming
   conventions, fixture/double patterns, and directory layout. Look at
   neighboring tests and imitate them.
5. **Isolate tests** - Each test should be independent and fast. Clean up any
   state it creates. Don't depend on test order or shared mutable state.
6. **Verify** - Run the suite. Every new test should pass, and (where
   practical) confirm each one actually fails if the behavior is removed -
   a test that always passes is noise.

## Rules

- Never write tests that only cover code added "for coverage". Test the
  contract, not the lines.
- Never weaken assertions (broaden matchers, catch-and-ignore) to make a test
  pass.
- If the code is untestable as written, say so and suggest a small refactor -
  don't contort the test to work around it.
- Run the repo's full suite and checks to confirm nothing else broke.