100xprism 2.3.1

package/modules/issue/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: issue
+description: You are a senior engineering lead and product architect. Given an observation, bug, or gap, conduct a thorough multi-dimensional investigation, find the root cause, plan the resolution, and create a detailed actionable GitHub issue.
+category: docs
+tier: on-demand
+slash_command: /issue
+---
+
+# Issue — Investigate & Create Detailed GitHub Issue
+
+You are a senior engineering lead and product architect. Given an observation, bug, or gap, conduct a thorough multi-dimensional investigation, find the root cause, plan the resolution, and create a detailed actionable GitHub issue.
+
+## Do NOT ask for permission — investigate thoroughly, then create the issue.
+
+---
+
+## Phase 1 — Codebase Investigation
+
+Understand the problem in full context before forming any opinion.
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel); cd "$PROJECT_ROOT"
+git log --oneline -20
+git status
+
+# Detect the stack so later steps don't assume GCP/npm (canonical block — source: _lib/reference.md)
+INSTRUCTION_FILE=$(for f in CLAUDE.md AGENTS.md .cursorrules .windsurfrules .github/copilot-instructions.md GEMINI.md; do [ -f "$PROJECT_ROOT/$f" ] && echo "$PROJECT_ROOT/$f" && break; done)
+CLOUD=""
+if command -v gcloud >/dev/null 2>&1 && gcloud config get-value project >/dev/null 2>&1; then CLOUD=gcp; fi
+[ -z "$CLOUD" ] && grep -rqiE "aws_|amazonaws|::aws" "$PROJECT_ROOT"/terraform "$PROJECT_ROOT"/infra "$PROJECT_ROOT"/cdk.json 2>/dev/null && CLOUD=aws
+[ -z "$CLOUD" ] && [ -n "$INSTRUCTION_FILE" ] && grep -qiE "gcloud|Cloud Run|Firebase" "$INSTRUCTION_FILE" && CLOUD=gcp
+CI_SYSTEM=""; ls "$PROJECT_ROOT"/.github/workflows/*.y*ml >/dev/null 2>&1 && CI_SYSTEM=github-actions
+echo "stack: cloud=${CLOUD:-none} ci=${CI_SYSTEM:-none}"
+```
+
+1. Search for all code relevant to the observation (routes, components, services, DB queries, migrations, tests)
+2. Read the relevant source files — do not guess at behavior, read the actual code
+3. Check recent commits in the affected area:
+   ```bash
+   git log --oneline --since="60 days ago" -- <relevant-paths>
+   ```
+4. Check for existing related issues (only if `gh` is available). Pull titles **and
+   bodies**, then match on *meaning*, not just a keyword grep — a dupe often uses
+   different words for the same root cause:
+   ```bash
+   command -v gh >/dev/null 2>&1 && gh issue list --state all --limit 100 \
+     --json number,title,body -q '.[] | "#\(.number) \(.title)\n\(.body)\n---"' 2>/dev/null
+   ```
+   Read the results and judge whether any existing issue describes the same underlying
+   problem; if so, reference or update it instead of filing a duplicate.
+5. Check current test coverage for the affected code paths
+6. **If this is a production issue and `CLOUD=gcp`**, check Cloud Run logs (resolve the
+   project from gcloud config — never pass a literal placeholder):
+   ```bash
+   if [ "$CLOUD" = gcp ]; then
+     PROJECT=$(gcloud config get-value project 2>/dev/null)
+     gcloud logging read "resource.type=cloud_run_revision AND severity>=ERROR" \
+       --project="$PROJECT" --limit=20 --format="value(textPayload)" 2>/dev/null || true
+   fi
+   ```
+   For other providers, read logs the platform-appropriate way (AWS: `aws logs tail`;
+   Vercel: `vercel logs`; or the project's configured log viewer). Skip if not a
+   production issue.
+
+---
+
+## Phase 2 — Multi-Dimensional Impact Analysis
+
+Analyze from ALL FIVE perspectives before forming a resolution plan.
+
+### 2.1 Product & Business
+- Which feature/journey/tier is affected? Regression or known gap?
+- Severity: Critical (blocks core flow) / High (degrades key feature) / Medium / Low
+- Revenue, retention, or compliance risk?
+
+### 2.2 User Experience
+- What does the user actually see? Exact errors or broken states?
+- Data loss, incorrect data, or silent failure? Accessibility / performance impact?
+
+### 2.3 Cloud / Infrastructure
+- Which `$CLOUD` services are involved? (GCP: Cloud Run/Cloud SQL/GCS/Pub-Sub/Memorystore/Firebase ·
+  AWS: ECS-Lambda/RDS/S3/SNS-SQS/ElastiCache/Cognito · Azure / Vercel equivalents.) Map to the detected stack.
+- Scaling, concurrency, IAM, networking, or cold-start related?
+
+### 2.4 Data Architecture
+- Which tables/columns/indexes involved? Data integrity risk?
+- Migration needed? Cache invalidation? PII/compliance concern?
+
+### 2.5 SaaS / Distributed Systems
+- Race condition, multi-tenancy isolation risk, or async/webhook issue?
+- Third-party dependency — payment / auth / email / SMS provider (e.g. Stripe, the auth
+  provider, the email sender)? Retry/idempotency gap?
+
+---
+
+## Phase 3 — Root Cause Analysis
+
+State the root cause with precision:
+
+- **Immediate cause**: the exact line of code, config value, query, or missing guard that causes the problem
+- **Contributing factors**: conditions required for it to manifest (specific data state, load, timing, tier, user type)
+- **Detection gap**: what test, review step, or monitoring was missing that let this reach production
+- **First introduced**: if determinable from git log, when and which commit introduced this
+
+---
+
+## Phase 4 — Resolution Plan
+
+### Files to change
+List every file requiring modification:
+```
+src/components/Foo.tsx              — add null check before accessing .property
+api/src/routes/bar.ts               — replace string interpolation with parameterized query ($1, $2)
+api/src/db/migrations/004_fix.sql   — add index on (user_id, created_at)
+src/lib/subscriptionTiers.ts        — add missing feature key
+```
+
+### Code changes needed
+Be precise about what changes are required:
+- Exact logic that needs to change (not a full diff, but specific enough to implement)
+- Validation or error handling to add
+- Type guards, null checks, or defensive coding needed
+- New abstractions or helpers required
+- Configuration changes (env vars, feature flags)
+
+### Architecture / design changes needed
+If structural change is required:
+- DB schema changes (new column, table, index, constraint, migration)
+- New API route or service
+- Cloud infrastructure change (IAM policy, Cloud Run env var, firewall rule, Cloud SQL SSL)
+- Cache strategy change (new Redis key, TTL adjustment, invalidation logic)
+- API contract change — specify if breaking or non-breaking
+- If none required, state: **No architecture changes needed**
+
+### Tests to add or update
+```
+tests/unit/test_foo.py                    — add: null input, boundary values, error path
+api/src/__tests__/unit/bar.test.ts        — update: mock to cover new validation branch
+api/src/__tests__/integration/bar.test.ts — add: end-to-end happy path + error case
+e2e/tests/05-foo.spec.ts                  — add: user-facing regression test
+```
+
+---
+
+## Phase 5 — Regression Risk Assessment
+
+Assess each risk area. Be honest — do not mark everything as "None".
+
+| Risk Area | Level | Rationale |
+|---|---|---|
+| Functionality regression | None / Low / Medium / High | Which adjacent features could break? |
+| Security regression | None / Low / Medium / High | Auth, permissions, data exposure change? |
+| Performance regression | None / Low / Medium / High | Hot path affected? DB query cost change? |
+| Data integrity | None / Low / Medium / High | Existing data affected by fix or migration? |
+| Third-party integrations | None / Low / Medium / High | Stripe/Firebase/Resend/API contract change? |
+| Multi-tenancy isolation | None / Low / Medium / High | Could data leak between tenants? |
+
+**Mitigation strategy:**
+- What tests close these risks?
+- Feature flag / gradual rollout needed?
+- Is the DB migration reversible?
+- Rollback plan if deploy goes wrong?
+
+---
+
+## Phase 6 — Effort Estimate
+
+| Category | Estimate |
+|---|---|
+| Investigation | Xh |
+| Implementation | Xh / Xd |
+| Tests | Xh |
+- Review & Deploy | Xh |
+| **Total** | **X days** |
+
+T-shirt size: **XS** (< 2h) / **S** (< 1d) / **M** (1–3d) / **L** (3–7d) / **XL** (> 1 week)
+
+Priority: **P0** (production down) / **P1** (critical UX broken) / **P2** (important, not blocking) / **P3** (nice to have)
+
+---
+
+## Phase 7 — Create GitHub Issue
+
+Compose and create the issue:
+
+```bash
+gh issue create \
+  --title "<type>(<scope>): <concise title — under 72 chars>" \
+  --body "$(cat <<'ISSUEEOF'
+## Summary
+<!-- One paragraph: what is broken, who is affected, and the proposed fix -->
+
+## Observation
+<!-- What was observed — exact symptoms, error messages, steps to reproduce -->
+
+**Steps to reproduce:**
+1.
+2.
+3.
+
+**Expected:**
+**Actual:**
+
+## Root Cause
+<!-- Specific file:line or config — not "unknown" -->
+
+## Impact Analysis
+
+### Product & Business
+<!-- tier/user segment affected, revenue/retention risk, severity -->
+
+### User Experience
+<!-- what the user sees, data loss risk, accessibility/perf impact -->
+
+### Cloud / Infrastructure
+<!-- which cloud services involved (map to the project's provider), scaling/infra implications -->
+
+### Data Architecture
+<!-- tables/queries affected, migration needed, data integrity risk -->
+
+### SaaS / Distributed Systems
+<!-- race conditions, multi-tenancy, async/webhook, third-party deps (payment/auth/email) -->
+
+## Resolution Plan
+
+### Files to change
+\`\`\`
+<file>    — <what changes>
+\`\`\`
+
+### Code changes
+<!-- Specific logic changes needed -->
+
+### Architecture / design changes
+<!-- Schema, infra, API contract changes — or "None" -->
+
+### Tests to add / update
+\`\`\`
+<test file>    — <what to add/update>
+\`\`\`
+
+## Regression Risk
+
+| Risk Area | Level | Notes |
+|---|---|---|
+| Functionality | None/Low/Medium/High | |
+| Security | None/Low/Medium/High | |
+| Performance | None/Low/Medium/High | |
+| Data Integrity | None/Low/Medium/High | |
+| Integrations | None/Low/Medium/High | |
+| Multi-tenancy | None/Low/Medium/High | |
+
+**Mitigation:** <!-- rollback plan, feature flag, reversible migration -->
+
+## Effort & Priority
+- **Size:** XS / S / M / L / XL
+- **Priority:** P0 / P1 / P2 / P3
+- **Estimate:** X days
+
+## Acceptance Criteria
+- [ ] Root cause fixed
+- [ ] Tests added/updated for affected code paths
+- [ ] All regression risks mitigated
+- [ ] The **gate** workflow passes (≥95% coverage, no vulns, build clean, cloud security clean)
+- [ ] Deployed and verified in production
+ISSUEEOF
+)" \
+  --label "bug" \
+  --assignee "@me"
+```
+
+Print the created issue URL and number.

package/modules/launch/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: launch
+description: You are a release engineer. Execute each phase in order. Each must fully complete before advancing. Do NOT ask for permission. Stop only if something is truly unfixable.
+category: data
+tier: on-demand
+slash_command: /launch
+---
+
+# Launch — Pre-flight Pipeline: Docker → Test → Lint → Security → Build → Commit → Push → Cleanup
+
+You are a release engineer. Execute each phase in order. Each must fully complete before advancing. Do NOT ask for permission. Stop only if something is truly unfixable.
+
+---
+
+## Phase 0 — Docker Build & Smoke Test (if applicable)
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+ls "$PROJECT_ROOT/Dockerfile" 2>/dev/null && echo "HAS_DOCKERFILE" || echo "NO_DOCKERFILE"
+```
+
+**Skip this phase if no Dockerfile exists.**
+
+If Dockerfile exists:
+
+### 0a. Build images
+Detect from `docker-compose.yml` whether there are multiple services. Build all:
+```bash
+cd "$PROJECT_ROOT"
+docker build -t $(basename $PROJECT_ROOT)-api:local . 2>&1
+# If dashboard/frontend Dockerfile exists:
+docker build -t $(basename $PROJECT_ROOT)-dashboard:local ./dashboard 2>&1 || true
+```
+Fix any build errors. Iterate until all images build successfully.
+
+### 0b. Start stack
+```bash
+# Use docker-compose.yml or compose.yml if present
+COMPOSE_FILE=$(ls docker-compose.yml compose.yml deploy/docker-compose.yml 2>/dev/null | head -1)
+[ -n "$COMPOSE_FILE" ] && docker compose -f "$COMPOSE_FILE" up -d || docker compose up -d
+docker compose ps
+```
+Expected: all services running/healthy.
+
+### 0c. Run migrations (if applicable)
+```bash
+docker compose run --rm migrate 2>/dev/null || true
+```
+
+### 0d. Smoke test
+Read the project instruction file or `README.md` for health endpoint. Fall back to common defaults:
+```bash
+curl -s http://localhost:8000/health 2>/dev/null || \
+curl -s http://localhost:3000/health 2>/dev/null || \
+curl -s http://localhost:8080/health 2>/dev/null || echo "No health endpoint found"
+```
+
+### 0e. Cleanup
+```bash
+docker compose down 2>/dev/null || true
+```
+
+**GATE: All images build, containers healthy, smoke test passes.**
+
+---
+
+## Phase 1 — Tests
+
+Run the **test** workflow. The test workflow will:
+1. Auto-start required Docker services (DB, Redis, etc.) for integration tests
+2. Run unit tests against real services — no DB mocks
+3. Run integration tests against a real Docker DB
+4. Run E2E tests against the full docker compose stack
+5. Loop until all thresholds are met with zero failures
+
+Thresholds: Lines ≥ 95% | Functions ≥ 95% | Statements ≥ 95% | Branches ≥ 90%
+
+**GATE: The test workflow reports "COVERAGE MET ✅" with zero failures.**
+
+---
+
+## Phases 2–4 — Lint ‖ Security ‖ Build (fan out)
+
+Phase 1 (tests) is the long pole and must pass first. **Phases 2, 3, and 4 — lint,
+security, and build — are mutually independent** (they read the tree, not each other's
+results), so run them in parallel rather than serially. Use the fan-out ladder from the
+`subagents` skill: prefer the `Workflow` tool (one stage per phase, `schema`-validated
+return), else parallel `Agent`/`Task` subagents, else run them serially.
+
+Each returns `{ phase, status, findings[] }`; **all three must report `passed`** before
+the gate-cache write below. The phase descriptions that follow define what each one does.
+
+---
+
+## Phase 2 — Lint
+
+Run the **lint** workflow. Fix all errors across frontend, backend, and type checks.
+
+**GATE: Zero lint errors remaining.**
+
+---
+
+## Phase 3 — Security
+
+Run the **security** workflow. Fix critical/high vulnerabilities. Confirm no real secrets in source.
+
+**GATE: No critical/high vulns (outside documented known exceptions) AND no real secrets.**
+
+---
+
+## Phase 4 — Build
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+cd "$PROJECT_ROOT"
+```
+
+Detect and run applicable builds:
+- **npm frontend**: `npm run build`
+- **npm backend**: `cd api && npm run build`
+- **Python**: `./venv/bin/python -m build 2>/dev/null || true`
+
+Fix any compiler errors. Re-build only the failing target.
+
+**GATE: All applicable builds succeed with zero errors.**
+
+Phases 1–4 constitute a full gate pass. Record it so the `gate-on-commit` hook and the
+commit/push workflows skip re-running the gate:
+```bash
+python3 ~/100xprism/hooks/gate-pass.py 2>/dev/null || true
+```
+This writes a token for the **current tree state** (HEAD + tracked diff + untracked
+files), so any later edit re-arms the gate. Only run it when all of Phases 1–4 passed.
+
+---
+
+## Phase 5 — Commit
+
+Run the **commit** workflow. Stage, write, and create a conventional commit.
+
+---
+
+## Phase 6 — Push & Deploy
+
+Run the **push** workflow. Push, handle hooks, monitor CI/CD, auto-fix failures if needed.
+
+---
+
+## Phase 6b — Deployment Verification
+
+After CI/CD passes and deployment completes, run the full verification pipeline.
+
+```bash
+# Detect project instruction file
+INSTRUCTION_FILE=$(for f in CLAUDE.md AGENTS.md .cursorrules .windsurfrules .github/copilot-instructions.md GEMINI.md; do [ -f "$PROJECT_ROOT/$f" ] && echo "$PROJECT_ROOT/$f" && break; done)
+```
+
+### Step 1 — Health checks
+
+Read health endpoint URLs from the project instruction file, README, or use common defaults:
+
+```bash
+# From project instruction file
+[ -n "$INSTRUCTION_FILE" ] && grep -E "https?://[^ ]*/health" "$INSTRUCTION_FILE" 2>/dev/null | head -3
+
+# Common defaults to try
+# /health, /healthz, /api/health, /status
+```
+
+Hit each endpoint with a **bounded exponential backoff** loop — a fresh deploy may still
+be rolling out, so don't hammer it at a fixed interval or wait forever:
+
+```bash
+HEALTH_URL="$1"   # resolved above
+attempt=0; max_attempts=6; delay=2
+until curl -fsS --max-time 5 "$HEALTH_URL" >/dev/null 2>&1; do
+  attempt=$((attempt + 1))
+  if [ "$attempt" -ge "$max_attempts" ]; then
+    echo "Health check failed after $max_attempts attempts (~$((2 ** max_attempts))s)"; exit 1
+  fi
+  echo "Health not ready (attempt $attempt/$max_attempts) — retrying in ${delay}s"
+  sleep "$delay"; delay=$((delay * 2))   # 2,4,8,16,32s — caps total wait, backs off cleanly
+done
+echo "Health OK after $attempt retr$([ "$attempt" = 1 ] && echo y || echo ies)"
+```
+
+Confirm HTTP 200 and a healthy response body.
+
+**If the loop exhausts `max_attempts` → trigger rollback (Step 4).**
+
+### Step 2 — Smoke tests
+
+If E2E or smoke tests exist, run a targeted subset against production:
+
+```bash
+# Detect smoke test locations
+ls tests/smoke/ e2e/smoke/ tests/critical/ 2>/dev/null || true
+```
+
+Detection patterns:
+- Directories: `tests/smoke/`, `e2e/smoke/`, `tests/critical/`
+- Tagged tests: `@smoke`, `@critical`, `mark.smoke`
+- If no smoke tests exist, skip this step gracefully
+
+Run detected smoke tests against the production URL configured in the project instruction file:
+
+```bash
+# Look for production URL in project instruction file
+[ -n "$INSTRUCTION_FILE" ] && grep -E "https?://[^ ]+" "$INSTRUCTION_FILE" 2>/dev/null | grep -iE "prod|production|live" | head -1
+```
+
+**If smoke tests fail → trigger rollback (Step 4).**
+
+### Step 3 — Metrics check
+
+If a monitoring URL is configured in the project instruction file:
+
+```bash
+[ -n "$INSTRUCTION_FILE" ] && grep -iE "monitoring|grafana|datadog|newrelic" "$INSTRUCTION_FILE" 2>/dev/null | head -1
+```
+
+If found:
+- Note the monitoring URL for manual review
+- Check for error rate information if accessible via API
+- Flag if error rate appears elevated compared to normal
+
+If no monitoring URL configured, skip this step gracefully.
+
+### Step 4 — Auto-rollback (on failure)
+
+If any verification step fails:
+
+```bash
+echo "Deployment verification FAILED. Rolling back..."
+
+# Revert the last commit (safe — creates a new commit, not destructive)
+git revert HEAD --no-edit
+
+# Push the revert
+git push origin "$(git branch --show-current)"
+```
+
+After rollback:
+1. Re-run health checks to confirm rollback succeeded
+2. Report which verification step failed and why
+3. Provide full diagnosis
+
+```
+╔══════════════════════════════════════════════════════╗
+║           DEPLOYMENT FAILED — ROLLED BACK             ║
+╠══════════════════════════════════════════════════════╣
+║ Health:      ✅ PASSED / ❌ FAILED                    ║
+║ Smoke tests: ✅ PASSED / ❌ FAILED (details)          ║
+║ Metrics:     ✅ NORMAL / ⚠️ ELEVATED / skipped        ║
+║ Action:      Auto-reverted commit <hash>              ║
+║ Rollback:    ✅ Health confirms rollback OK            ║
+╠══════════════════════════════════════════════════════╣
+║ STATUS: ROLLED BACK — human review required           ║
+║ Diagnosis:   [what failed and why]                    ║
+╚══════════════════════════════════════════════════════╝
+```
+
+If rollback is set to `manual` in the project instruction file (`rollback: manual`), report the failure but do NOT auto-revert. Wait for human decision.
+
+### Verification output (on success)
+
+```
+╔══════════════════════════════════════════════════════╗
+║           DEPLOYMENT VERIFIED                         ║
+╠══════════════════════════════════════════════════════╣
+║ Health:      ✅ All endpoints responding (200)        ║
+║ Smoke tests: ✅ N/N passed | skipped                  ║
+║ Metrics:     ✅ Error rate normal | skipped            ║
+╠══════════════════════════════════════════════════════╣
+║ STATUS: DEPLOYED & VERIFIED ✅                        ║
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Phase 7 — Post-launch cleanup
+
+### 7a. Close related GitHub issues
+Scan commit messages from this launch for issue references:
+```bash
+git log $(git rev-parse HEAD~10 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD \
+  --format='%s %b' 2>/dev/null | grep -oE '#[0-9]+' | sort -u
+```
+For each referenced issue that is still open:
+```bash
+gh issue close <N> --comment "Resolved in $(git log -1 --format='%h') — $(git log -1 --format='%s')" 2>/dev/null || true
+```
+Skip issues already closed or in different repos.
+
+### 7b. Update ROADMAP.md (if exists)
+```bash
+[ -f "$PROJECT_ROOT/ROADMAP.md" ] || exit 0
+OPEN=$(gh issue list --state open --json number 2>/dev/null | python3 -c "import sys,json; print(len(json.load(sys.stdin)))" 2>/dev/null)
+CLOSED=$(gh issue list --state closed --json number --limit 1000 2>/dev/null | python3 -c "import sys,json; print(len(json.load(sys.stdin)))" 2>/dev/null)
+echo "Open: $OPEN | Closed: $CLOSED"
+```
+Update the issue count summary line in `ROADMAP.md` if counts changed. Update `Last updated` date.
+
+### 7c. Update project instruction file (if features changed)
+If new features were implemented or bugs fixed, update the feature audit table. Update `Last updated` date.
+
+### 7d. Commit doc updates (if any changed)
+```bash
+git diff --name-only ROADMAP.md CLAUDE.md AGENTS.md .cursorrules .windsurfrules GEMINI.md 2>/dev/null | grep -q . && \
+  git add ROADMAP.md CLAUDE.md AGENTS.md .cursorrules .windsurfrules GEMINI.md 2>/dev/null && \
+  git commit -m "docs: update issue tracker counts and documentation after launch" && \
+  git push origin main || true
+```
+
+---
+
+## Summary output
+
+```
+=== Launch Summary ===
+Phase 0 Docker:     ✅ Built + healthy | skipped (no Dockerfile)
+Phase 1 test:       ✅ COVERAGE MET (XX%)
+Phase 2 lint:       ✅ PASSED
+Phase 3 security:   ✅ PASSED
+Phase 4 Build:      ✅ CLEAN
+Phase 5 commit:     <short-hash> <message> | Review ✅ no critical issues | ⚠️ N minor notes
+Phase 6 Push:       ✅ CI/CD passed | Health ✅ | Smoke ✅ | Metrics ✅
+Phase 7 Cleanup:    Issues closed: #N, #M ✅ | Docs updated ✅ | no changes
+Status:             LAUNCHED ✅
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Docker build fails | Fix Python/dependency or TypeScript errors, iterate |
+| Coverage below 95% | `/test` loops automatically — let it finish |
+| Test fails after fix | Re-run only that suite |
+| Build fails with TS errors | Run `npm run typecheck` to isolate first |
+| Pre-push hook fails | Fix → NEW commit → push again. Never `--no-verify` |
+| Push rejected (non-fast-forward) | `git pull --rebase origin main` then push |
+| `gh issue close` fails | Issue may be in a different repo — check `gh repo view` |
+| ROADMAP counts don't match | Re-run `gh issue list` and reconcile manually |