issue

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.