Claude.md 1

gistfile1.txt

# Workflow

## Handling Errors and Blockers

When you hit a blocker, or something that isn't working as expected in your dev environment: **stop immediately**, report it to the user, and wait for input. Do not attempt some hacky workaround. Fail fast.

This applies to especially to tooling and E2E failures.

## Non-Software Research Workflow

- For research, shopping, travel, email, and other non-software-dev tasks, the fail-fast dev-environment blocker rule does not apply. Keep working through ordinary site/tooling friction and report only true blockers.
- If the in-app browser is blocked or unreliable during research, use the regular Chrome browser as the fallback.

## Rules and Procedures

- Do not jump to implementation if the user asks you a question about your approach.  Questions like "can we just do X?" or "what if we Y?" are invitations to discuss, not green lights to execute.
- Before introducing a new abstraction, pause and discuss it with the user. Major design decisions — especially new services, classes, framework boundaries, persistence patterns, or other architecture-shaping abstractions — should be explicitly flagged with the tradeoffs before implementation.

## Git Workflow

- Default workflow: make local changes, verify them, and stop for user review.
- Do not commit, push, open PRs, merge branches, tag releases, or publish artifacts unless the user explicitly asks for that specific action.
- The user owns the final integration step by default. They may review and commit themselves, or ask you to commit/push/merge afterward.
- It is OK to work directly on the current branch, including `main`, when that is where the user has placed the worktree. Do not switch branches unless the user asks or the repo workflow explicitly requires it.
- Never force push. Never push directly to `main` unless explicitly instructed.
- If asked to commit, commit only the intended changes and report the exact commit hash.
- If asked to push, push only the requested branch/ref and report what was pushed.

## Local CI Work Loop

For substantial implementation work, broad bug fixes, or changes with meaningful behavior risk:

1. Understand the request and relevant context.
2. Make the code/spec/test changes locally.
3. Run project-defined formatting, linting, and typechecking.
4. Run relevant tests for the change.
5. Run manual/E2E verification when the change has integration or UI risk.
6. Stop with a review-ready summary: changed files, verification results, remaining risks, and anything not run.

For small, mechanical, or narrowly scoped fixes, use the lightweight loop:

1. Make the change.
2. Sanity-check the exact diff.
3. Run project-defined formatting, linting, and typechecking.
4. Run targeted tests when behavior could be affected.
5. Stop for review.

Always run formatting, linting, and typechecking before presenting code as ready, unless a blocker prevents it. Report blockers immediately.

Use the full loop when the change introduces or changes architecture, persistence, migrations, user-facing behavior, important business logic, cross-module contracts, or more than a couple files. Use the lightweight loop for typo fixes, import-path fixes, small test updates, config/docs wording, and other localized changes with low behavioral risk.

Do not commit or push at the end of either loop unless explicitly asked.

## Review Handoff

When work is ready for review, summarize:

- What changed.
- Why it changed.
- Tests/checks run.
- Manual or E2E verification performed.
- Files changed.
- Any known risks or follow-up decisions.

Do not phrase uncommitted work as "landed," "merged," or "released." Use those words only after the corresponding git or release action actually happened.

# Coding Guidelines

## Core Principles

We write Clean Code at the proper level of abstraction. Not prematurely over-abstracted, and not under-abstracted either.

### KISS: KEEP IT SIMPLE, STUPID.

- Perform the smallest change that accomplishes the user's goals. Simplicity is a virtue. Bias towards fewer lines of code, fewer files.

### AVOID "BELT AND SUSPENDERS" or overly defensive approaches.

- If you find yourself describing code as a “belt,” “guard,” “extra safety,” or “future accidental broad copy” protection, stop and ask whether it is duplicating the primary fix.

### DRY: Do Not Repeat Yourself

- Avoid duplicating code. Pull out functions as necessary. Pull out and refactor shared utilities as needed.

### Separation of Concerns

- Modules should not know about the inner and workings of other modules. 

### Name Files and Functions Thoughtfully

- Names are incredibly important for codebase comprehension. In particular, function names should accurately describe what the function does, within reason. Prefer longer function names that describe functions and side effects versus shorter function names, within reason.

### Leave the Campground Cleaner Than You Found It

There will almost always be opportunities to improve existing code structure, implementation, etc, as part of your feature work. As long as these are not *major* refactoring tasks, you should undertake them as you go.

If you *do* spot a major refactoring task, you should call it out to your user.

### Follow existing practices and conventions in the codebase.

- Principle of least surprise: your code should look like related code and follow existing patterns. Explore the codebase as needed to understand the existing patterns.

## Coding Style

### Comments and docstrings

- **Do** add a comment or docstring line when the *reason* behind a decision isn't obvious from the code alone — e.g., a surprising filter, a non-obvious workaround, a business rule that can't be inferred by reading the surrounding code, or an invariant the type system can't express.
- New abstractions, classes, etc generally deserve docstrings.
- **Do not** add zero-value comments that restate what the code obviously does.

### Step-by-step procedural flows

- When a function has a clear "do X, then Y, then Z" workflow, separate each phase with a blank line and a short comment that explains the purpose, ordering constraint, or risk of that phase. These phase comments are valuable even when the statements inside the block are individually simple.
- This does not conflict with avoiding zero-value comments: "copy the prompt map" is noise, but "snapshot the prompt map before cleanup removes it from config" documents why the step exists at that point in the sequence.

### Inline single-use logic blocks

- Prefer keeping a cohesive block of logic inline when it is used only once. Do not extract a single-use helper just to name the block. Instead, put a concise comment immediately above the block explaining the purpose or non-obvious behavior, and keep a blank line before that comment so the block reads as a distinct unit.
- Use this shape for adjacent inline blocks:

```
previous_statement()

# Explanation of block 1
functionality_block_1
...
...

# Explanation of block 2
functionality_block_2
...
...
```

### Avoid functions with many positional arguments

- For >3 arguments, we should use a typed arguments object.


### Specific conventions

- Avoid Nesting The Happy Path; return early in error checks.
- Don't Declare Unnecessary Variables: if you're declaring a variable then using it again on the next line, just pass it directly.
- Prefer explicit mapping tables when translating between enumerated option values. Do not hide product/API mappings inside nested conditionals when a map can make every supported value visible at a glance.
- In Python, module-level constants should use `UPPER_SNAKE_CASE`. Lowercase module-level names should not be used for fixed constants.

# System Design

## Critical systems should fail fast

Example: if your server relies on Alembic to perform migrations, don't simply put a warning log if the alembic directory is missing; the server should fail to start, it's obvious that something went very wrong.

Do not use fallback defaults to paper over missing invariant data. If a database migration promises a singleton row, seed record, schema table, or required persisted setting, code should fail fast when it is missing instead of silently reconstructing or substituting values. Silent fallback in these cases is overly defensive programming and hides broken migrations or corrupted state.

# Debugging Strategies

## Root Cause Analysis and Fixes

- It's not enough to simply 'fix' an issue: you need to make the RIGHT fix.
- Do not simply 'add more code' to paper over an issue. You must find the root cause: often this will involve a design change. 
- You should ask clarifying questions to the user rather than making assumptions.
- Don't just speculate as to the root cause of issues. You need to actually think through it properly and consider where you're making assumptions. You MUST find the root cause in order to make a proper fix.

## Search for known issues before first-principles investigation

When debugging anything involving a third-party runtime, SDK, framework, or library, the **first** step — before writing local repros, reading source, doing bisection, building custom tooling, or forming hypotheses about our code — is a **targeted web search for the symptom against that library's issue tracker and release notes**.

# Workflow