Issue — Investigate & Create Detailed GitHub Issue

Given an observation, bug, or gap: investigate multi-dimensionally, 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.

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; 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 — never guess at behavior
3. Check recent commits in the affected area:

   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:

   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
   

   If an existing issue describes the same underlying problem, reference or update it instead of filing a duplicate.
5. Check current test coverage for the affected code paths
6. If a production issue and CLOUD=gcp, check Cloud Run logs (resolve the project from gcloud config — never pass a literal placeholder):

   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 planning a resolution.

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:

• Exact logic 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:

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.