feat: GTFS streaming import, realtime retention, heatmap perf, frontend UI overhaul, and reliability fixes

.claude/skills/atomic-commits/SKILL.md

@@ -7,25 +7,32 @@ description: Plan and create organized atomic commits with clear Conventional Co
 
 Create a small set of self-contained commits with descriptive messages and verified checks.
 
+---
+
 ## Workflow
 
-### Step 1: Analyze Changes
+### Step 1: Gather State (no destructive actions)
 
-Gather information about the current state:
+Inspect the current state of the repository:
 
 ```bash
+# Goal: identify all modified, staged, and untracked files that belong to this change set
 git status
-git diff
-git diff --staged
+git diff            # all unstaged modifications
+git diff --staged   # any previously staged changes
 git log --oneline -10
-
-# Clear staging area to ensure clean slate for atomic commits
-git reset
 ```
 
+**GUARD: Do NOT run `git reset` here.** If there are already staged changes:
+
+1. Ask the user: _"You have N files already staged. Should I unstage before planning, or plan around them?"_
+2. Only unstaged if the user explicitly says to — and even then, use `git reset HEAD -- <file>` per-file, never a bare `git reset`.
+
+If the staging area is clean, proceed directly to Step 2.
+
 ### Step 2: Plan Atomic Commits
 
-Analyze the changes and group them into logical atomic commits. Each commit should:
+Analyze the diffs and group changes into logical atomic commits. Each commit should:
 
 - Be self-contained and buildable
 - Contain logically related changes
@@ -41,84 +48,82 @@ Analyze the changes and group them into logical atomic commits. Each commit shou
 
 Common commit types:
 
-- `feat:` - New feature
-- `fix:` - Bug fix
-- `refactor:` - Code refactoring (no behavior change)
-- `chore:` - Maintenance tasks, dependencies, config
-- `docs:` - Documentation changes
-- `test:` - Test changes
-- `build:` - Build system or dependency changes
-- `perf:` - Performance improvements
+- `feat:` — New feature
+- `fix:` — Bug fix
+- `refactor:` — Code refactoring (no behavior change)
+- `chore:` — Maintenance tasks, dependencies, config
+- `docs:` — Documentation changes
+- `test:` — Test changes
+- `build:` — Build system or dependency changes
+- `perf:` — Performance improvements
 
-### Step 3: Present the Plan
+For each planned commit, identify which **functions, classes, or sections** belong to it (not just which files). This will be used later to verify that the right hunks are staged.
 
-Before committing, present the planned commits to the user in a clear format:
+### Step 3: Run All Checks and Resolve Issues
 
-```
-Planned commits (N total):
+**Do this BEFORE presenting the plan to the user**, because `pre-commit --all-files` may auto-modify files (e.g., formatting), which can change the commit plan.
 
-1. [type]: brief description
-   Files: path/to/file1, path/to/file2
-   Details: explanation of what changes and why
+Run checks ONCE for all changes:
 
-2. [type]: brief description
-   Files: path/to/file3
-   Details: explanation of what changes and why
+```bash
+pre-commit run --all-files
 ```
 
-Ask for user confirmation before proceeding.
+If this repo uses `direnv`, ensure it is allowed before running. Otherwise activate the dev env (often `source .dev-env`) before running Python tooling.
 
-### Step 4: Run All Checks ONCE (Before Creating Commits)
+**If checks pass:** proceed to Step 4.
 
-**IMPORTANT:** Run checks ONCE for all changes before starting to create commits. Pre-commit will run again during each `git commit`, so this catches issues upfront and avoids repeated runs.
+**If checks fail:**
 
-```bash
-# Run pre-commit on all files (catches linting, type-check, test issues)
-pre-commit run --all-files
-```
+1. Fix the issues.
+2. Re-run `pre-commit run --all-files` (not individual checks).
+3. If checks still fail after **3 fix attempts**, **STOP** and report the failure to the user with the full output. Ask for direction. Do not loop beyond 3 attempts.
+4. **CRITICAL: Do NOT proceed to create commits until all checks pass.**
 
-If this repo uses `direnv`, ensure it is allowed before running. Otherwise activate the dev env (often `source .dev-env`) before running Python tooling.
+After checks pass, re-examine the plan from Step 2. If `pre-commit` auto-modified any files, adjust the commit groupings accordingly before presenting.
 
-**Why this approach:**
+### Step 4: Present and Confirm the Plan
 
-- Pre-commit already runs linting, type-checking, and tests
-- Running once before committing is more efficient than per-commit
-- Prevents the pre-commit hook from failing mid-commit sequence
+Present the verified plan to the user:
 
-Continue to Step 5 only after all checks pass.
+```
+Planned commits (N total):
 
-### Step 5: Resolve Issues
+1. [type]: brief description
+   Scope: <functions/sections this commit covers>
+   Files: path/to/file1, path/to/file2
+   Details: explanation of what changes and why
 
-If `pre-commit run --all-files` fails:
+2. [type]: brief description
+   Scope: <functions/sections this commit covers>
+   Files: path/to/file3
+   Details: explanation of what changes and why
+```
 
-1. Fix the issues
-2. Re-run `pre-commit run --all-files` (not individual checks)
-3. Repeat until all checks pass
-4. **CRITICAL: Do NOT proceed to create commits until all checks pass**
-5. Only then proceed to Step 6
+Ask for user confirmation before proceeding.
 
-### Step 6: Create Commits
+### Step 5: Create Commits
 
-**GUARD: Only proceed here after ALL pre-commit checks have passed.**
+**GUARD: Only proceed here after the user has confirmed the plan AND all pre-commit checks have passed.**
 
-Create commits one at a time, staging only the files for each commit:
+Create commits one at a time. For each planned commit:
 
 ```bash
-# For each planned commit:
+# Stage only the files for this commit
 git add <files-for-this-commit>
 
-# CRITICAL: Verify what will actually be committed before committing
-git diff --cached
+# CRITICAL: Verify what will actually be committed
+git diff --cached    # Goal: confirm staged hunks match ONLY this commit's scope
 ```
 
 **Review the staged diff carefully:**
 
-- Does it contain ONLY the changes described in this commit?
-- Are there unrelated changes bundled in? (especially if a file has multiple logical changes)
-- If wrong changes are staged, use `git reset` and re-stage more carefully
-- For files with multiple independent changes, consider using `git add -p` to stage specific hunks
+- Does it contain ONLY the changes described in this commit's scope?
+- Are there unrelated changes bundled in? (especially if a single file has changes for multiple commits)
+- If wrong changes are staged, use `git reset HEAD -- <file>` to unstage that specific file, then re-stage more carefully.
+- Do NOT use bare `git reset` — it unstages ALL files and destroys your commit-in-progress.
 
-Only AFTER verifying the staged diff matches the planned commit:
+After verifying the staged diff matches the planned commit:
 
 ```bash
 git commit -F - <<'EOF'
@@ -129,21 +134,28 @@ git commit -F - <<'EOF'
 EOF
 ```
 
-**IMPORTANT:**
+**GUARD: If `git commit` fails** (e.g., pre-commit hook rejects it):
+
+1. Do NOT amend — fix the issue and create a new commit attempt.
+2. If the failure suggests the plan was wrong, **stop the sequence**, report what commits were created and what failed, and ask the user how to proceed.
+3. Only continue to the next planned commit after the current one succeeds.
+
+**Rules for creating commits:**
 
-- Always verify with `git diff --cached` BEFORE committing
-- Always use HEREDOC syntax for commit messages to ensure proper formatting
-- Each commit must be created separately (never batch multiple logical commits)
-- Do NOT use `git commit --amend` - always create new commits
-- Do NOT push commits - the skill only creates them locally
-- Pre-commit hooks will run during each `git commit` (but should pass since you ran `--all-files` first)
+- Always verify with `git diff --cached` BEFORE committing.
+- Always use HEREDOC syntax for commit messages.
+- Each commit must be created separately (never batch multiple logical commits).
+- Do NOT use `git add -p` or any interactive command — use file-level staging only.
+- Do NOT use `git commit --amend` — always create new commits.
+- Do NOT push commits — the skill only creates them locally.
+- Pre-commit hooks will run during each `git commit`. This is expected and safe because you already passed `--all-files` in Step 3.
 
-### Step 7: Verify and Report
+### Step 6: Verify and Report
 
 After all commits are created:
 
 ```bash
-# Show the commits created
+# Goal: confirm all intended commits were created and working tree is clean
 git log --oneline -10
 git status
 ```
@@ -152,12 +164,12 @@ Report to the user:
 
 - Number of commits created
 - Brief summary of each commit
-- Confirmation that tests passed
+- Confirmation that checks passed
 - Reminder that commits are local and not pushed
 
-## Example Output
+---
 
-After completing, report to the user like this:
+## Example Output
 
 ```
 ✓ Created 3 atomic commits:
@@ -176,15 +188,19 @@ After completing, report to the user like this:
      - Added authentication flow diagrams
      - Documented token refresh mechanism
 
-All tests passed. Commits are ready locally (not pushed).
+All checks passed. Commits are ready locally (not pushed).
 ```
 
-## Important Notes
+---
 
-- **NEVER commit without verifying** - Always run `git diff --cached` after staging and BEFORE committing to verify exactly what will be committed
-- **Never skip tests** - Always run the full test suite before committing
-- **Never push** - This skill only creates local commits
-- **Always use HEREDOC** for commit message formatting
-- **Always create new commits** - never amend existing ones
-- **Group logically** - Atomic commits should be self-contained units
-- **Follow project style** - Match existing commit message patterns
+## Troubleshooting
+
+| Problem                                             | Action                                                                                                                                                                                             |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| User had pre-staged work                            | Ask whether to preserve or unstage before planning. Unstaged per-file with `git reset HEAD -- <file>`, never bare `git reset`.                                                                     |
+| `pre-commit --all-files` fails                      | Fix and re-run. After 3 failed fix attempts, stop and ask the user.                                                                                                                                |
+| Auto-formatting changed files                       | Re-examine the commit plan — those changes may need different grouping.                                                                                                                            |
+| Wrong files staged for a commit                     | `git reset HEAD -- <file>` to unstage specific files, not bare `git reset`.                                                                                                                        |
+| `git commit` rejected by hook                       | Fix the issue, then create a new commit (never amend). If the fix changes the plan, stop the sequence and ask.                                                                                     |
+| A file has changes for multiple commits             | Split at file boundaries (whole-file per commit). Interactive `git add -p` is not supported; stage files as wholes only. If a file truly needs splitting, ask the user to split it manually first. |
+| Partial sequence failure (2 of 3 commits succeeded) | Report what was created and what failed. Ask user whether to continue, re-plan, or start over. Never amend already-created commits.                                                                |