Investigate — End-to-End GitHub Issue Workflow

Repo-agnostic workflow that takes a GitHub issue (bug or feature request) from reported state to an open pull request that closes the issue. Discover project conventions at runtime — assume no build commands, test runners, or languages.

Two execution modes:

• Interactive — ask the user (via AskUserQuestion) to resolve ambiguity.
• Non-interactive — running headlessly (claude -p, CI, automation). Never ask the user; on irreducible ambiguity, fail with a clear error rather than guess silently.

Treat "Can I reach the user right now?" as the deciding factor. If not, the run is non-interactive — surface the blocker and exit.

Bundled resources

The deterministic shell logic lives in scripts/; the design rationale lives in references/. Invoke a script by its absolute path. When loaded as a plugin, that path is ${CLAUDE_PLUGIN_ROOT}/investigate/scripts/<name>; if ${CLAUDE_PLUGIN_ROOT} is unset (skill loaded standalone), resolve scripts/ relative to this SKILL.md. The examples below abbreviate the prefix as scripts/.

• scripts/resolve-issue.sh — Phase 1 issue-number resolution.
• scripts/collect-instructions.sh — Phase 3.2 scoped-instruction walk over the changed paths' ancestors.
• scripts/git-safety-lib.sh — shared remote/default-branch resolvers (sourced by the two scripts below; never run directly).
• scripts/check-branch.sh — Phase 5.0 branch-safety guard.
• scripts/push-branch.sh — Phase 6 upstream-aware push.
• references/issue-number-resolution.md — Phase 1 rules, edge cases, and the two invariants the resolver enforces.
• references/scoped-instructions.md — Phase 3.2 precedence and merge rules, and why the walk is deferred until the plan's paths are known.
• references/git-safety.md — how the guard and push resolve the same remote and the repo's default branch, and why.

Phase 1 — Resolve the issue number

Run the resolver, passing the raw invocation argument (empty if none):

scripts/resolve-issue.sh "${ARGUMENTS:-}"

It accepts 123 or #123, else infers the number from the branch name, then verifies the issue exists. Act on its exit code:

• 0 — stdout is the issue number. Record it and continue.
• 2 — no number could be resolved; stdout is the current branch name.
  • Interactive: ask via AskUserQuestion — "What is the GitHub issue number to investigate?"
  • Non-interactive: fail with exactly this message (substitute the branch):

    investigate: no issue number provided and cannot infer from branch '<BRANCH>'. Re-run with the issue number, e.g. /investigate 123.

• 1 — hard failure (an explicit issue does not exist, or gh could not reach GitHub). The script already printed the specific message to stderr; relay it and abort.

The resolver deliberately never discards an explicit /investigate <N> silently, and only clears a branch-inferred guess on a confirmed "not found". See references/issue-number-resolution.md for the extraction rules and the release/2.0-issue-123 / dependabot/... / pr2024 / hotfix-1.2.3 cases.

Phase 2 — Fetch and classify the issue

Fetch the full issue:

gh issue view "$ISSUE" --json number,title,body,labels,state,comments

If the issue is already closed, stop and confirm the user wants to proceed before continuing.

Classify as bug or feature, in order:

1. Labels (strongest signal). Bug: bug, defect, regression, crash. Feature: enhancement, feature, feature-request, new feature.
2. Title/body keywords, if no decisive label. Bug: "expected … actual", "reproduce", "repro", "crash", "panic", "error", "fails", "broken", "regression", stack traces, version numbers. Feature: "would be nice", "support for", "add", "implement", "proposal", "feature request", "RFC".
3. Still ambiguous. Interactive: ask which workflow to follow. Non-interactive: default to the bug workflow (reproduction is harmless and reveals more context) and print: "Classified as bug by fallback heuristic; verify before merging."

Record the classification and proceed to the matching workflow.

Phase 3 — Discover project conventions

3.1 Baseline (top-level) conventions

Read the project's own instructions for how to build, test, lint, and commit:

cat CLAUDE.md AGENTS.md 2>/dev/null
ls README* CONTRIBUTING*

Also infer the toolchain from manifests:

• package.json → npm/yarn/pnpm scripts (test, lint, build, typecheck).
• Cargo.toml → cargo test, cargo clippy, cargo fmt --check, cargo build.
• pyproject.toml / setup.py → pytest, ruff/flake8, mypy/pyright, plus uv/hatch if present.
• go.mod → go test ./..., go vet, gofmt -l, go build ./....
• Makefile → test, lint, check, ci targets.
• pom.xml / build.gradle → mvn test / ./gradlew test.

Record the discovered test, lint/format-check, type-check, and build commands as the baseline check set. Prefer a project's own canonical command sequence (from CLAUDE.md / AGENTS.md) over the inferred defaults.

3.2 Scoped conventions along the changed paths

Repos with per-package or nested instructions (e.g. frontend/AGENTS.md) apply extra or overriding rules to the files beneath them, so the top-level baseline alone can miss the checks and commit rules that actually govern a change. This step needs to know which files you will touch, so it runs after Phase 4's plan settles the target paths (see 4A.4 / 4B.3), not now.

Once those paths are known, collect the instruction files along their ancestors:

scripts/collect-instructions.sh <changed-path> [<changed-path> ...]

It walks each path's directory up to the repo root and prints every CLAUDE.md / AGENTS.md it finds — deduplicated (symlink-aware) and ordered baseline (repo root) → closest (deepest). Read each file and merge with closest-wins precedence: the top-level file is the baseline; a nearer file overrides it on conflict and may add checks the baseline omits. When a scoped file changes or adds a command relative to the baseline, surface a one-line divergence note — which file, which command — so the validation command set is auditable rather than silently flattened. Feed the merged command set into the validation step (4A.6 / 4B.5).

Empty output (or exit 0 with nothing printed) means no scoped file governs the change — fall back to the 3.1 baseline alone. See references/scoped-instructions.md for the precedence rationale.

Phase 4 — Workflow dispatch

4A. Bug workflow

4A.1 Analyse. From the issue body and comments, extract the reported vs. expected behaviour, reproduction steps, inputs, environment notes, the affected version, and likely subsystem(s) from file paths, error messages, or stack traces.

4A.2 Reproduce. Build a minimal reproducer using the project's normal commands. Confirm the bug manifests locally before changing anything — keep the reproducer small and self-contained. When the repo has a test harness, write it as an automated test: that test is the red step of the test-first policy below, not a throwaway to be replaced later. If the bug cannot be reproduced, document the gaps. Interactive: ask for clarification. Non-interactive: comment on the issue describing what was tried and what failed, then exit documenting the blocker.

4A.3 Locate. Use grep/rg for error strings, function names, and log messages from the repro, then read the suspects. For non-trivial bugs (multiple files, subtle root cause), delegate to /pm-plan with a focused prompt describing the bug, the repro, and the symptom.

4A.4 Plan the fix. Write a concise numbered plan, each step citing file:line targets and the change to make (or use the /pm-plan output). Convert the plan to a task list with TaskCreate before executing — one task per reviewable unit. Once the target paths are settled, run Phase 3.2 (scripts/collect-instructions.sh) over them and fold the merged, closest-wins check set into the plan. List the test file path(s) alongside the production targets so 3.2 covers both.

4A.5 Fix (best effort). Apply the changes under the test-first policy below, starting from the 4A.2 test. Mark each task in_progress when starting it and completed the moment it is done — do not batch updates. On hitting a wall (mismatched assumptions, scope explosion, blocked by another bug), surface it: interactive — ask how to proceed; non-interactive — comment on the issue, leave the partial branch, exit. Do not open a half-finished PR.

4A.6 Validate. Run the merged check set from Phase 3 (the 3.1 baseline plus any 3.2 scoped instructions) in order — format/format-check, lint, type-check, tests, build — stopping and iterating on any failure. Loop until all are green, then proceed to Phase 5.

4B. Feature workflow

4B.1 Explore. Map the parts of the codebase the feature touches. Read the relevant modules, study existing patterns (naming, layering, error handling, test style), and note the conventions to mirror. For non-trivial features (multiple modules, new abstractions, data-model changes), delegate to /pm-plan and treat its output as the master plan.

4B.2 Resolve design questions. For any genuinely ambiguous decision (data model, API shape, UX, where the feature lives):

• Interactive: stress-test the design with the user. Use /grill-with-docs (or the simpler /grill-me) if available; otherwise list the open questions and resolve each via AskUserQuestion before writing code. Update the plan with the answers.
• Non-interactive: if the design is ambiguous, fail with exactly this message (substitute the issue number):

  investigate: feature request #<N> is ambiguous and cannot be designed non-interactively. Provide more details or run interactively.

  /pm-plan answers its own questions headlessly, so a guess on one of these decisions recorded in its ## Assumptions section counts as ambiguous.

If the request is concrete enough that no design choices remain open (e.g. "add a --quiet flag that suppresses progress output"), proceed without a design pass.

4B.3 Plan. As in 4A.4 — concise file:line step list, including test file paths, converted to a TaskCreate task list before execution (or the /pm-plan output).

4B.4 Implement (best effort). Follow the repo norms from 4B.1. Build testable behaviour under the test-first policy below, one failing test per behaviour. Mark tasks in_progress/completed as work progresses. Same blocker rules as 4A.5 — surface (interactive) or comment and exit (non-interactive); no half-finished PRs.

4B.5 Validate. As in 4A.6 — run the merged check set (Phase 3.1 baseline plus 3.2 scoped) in order; loop until green.

Test-first policy

Applies to 4A.5 and 4B.4. The practice is the default; /tdd is the preferred vehicle for it, and without /tdd the manual loop is the same: write the failing test, confirm it fails, then write the implementation.

• Red, then green. Write the failing test before the fix, run it, and confirm it fails for the reported reason. Make it pass with the smallest change, then refactor while green.
• Testability changes come first. If the test cannot be written without a production edit (exporting a private function, extracting a seam, injecting a dependency, adding an entry point), make that minimal, behaviour-preserving change first and keep it separate from the fix.
• A bad red step goes back to 4A.2. A test that passes immediately, or fails for another reason (setup, import, unrelated assertion), has not reproduced the bug. Fix the test, or take the 4A.2 cannot-reproduce path. Never weaken a test until it fails.
• Non-interactive runs do not re-confirm seams. /tdd asks the user to confirm the seams under test. With no user, the seam is the one the 4A.2 reproducer or the 4A.4/4B.3 plan already identified; treat it as pre-agreed.

When test-first does not fit. Skip it, and record the reason in the PR body (the test-plan line in Phase 6), when any of these hold:

• No usable test harness, or the code is out of the suite's reach (shell glue, build scripts, installers). Do not build a test framework to satisfy the policy.
• The change is docs, prose, config, build, CI or packaging, where there is nothing to assert or running the pipeline is the test.
• The failure is non-deterministic (races, timing, flakiness), so a failing test proves little.
• It needs real hardware, a specific OS, production data, or an external service that is unavailable.
• The fix is a dependency bump or vendored patch, so a test would exercise the library rather than this repo.
• It is a performance regression; use a benchmark with a threshold instead.
• It is a pure refactor or deletion; the existing tests are the safety net.
• It is a visual or UI defect that only a screenshot or manual check confirms.

Fall back to the best available check: the manual repro from 4A.2, or a before/after run of the relevant command, with the output summarised in the PR body. The fallback never blocks the fix.

Phase 5 — Commit

Step 5.0 — Branch safety guard

Before any git add, git commit, or git push, verify the worktree is on a topic branch — never the repo's default branch (whatever its name) and never a detached HEAD:

scripts/check-branch.sh

Act on its exit code:

• 0 — safe (topic branch, or the default branch could not be resolved but HEAD is not detached). Proceed to Step 5.1.
• 5 — refuse. stdout is the offending branch name (or detached HEAD).
  • Interactive: ask (AskUserQuestion) which topic branch to use. git switch <name> for an existing branch or git switch -c <name> for a new one, then re-run this guard.
  • Non-interactive: fail with exactly this message (substitute the stdout value) and exit without committing or pushing:

    investigate: refusing to commit/push from '<BRANCH-or-detached>'. Re-run on a topic branch (e.g. issue<N>) or pass the branch explicitly.

This guards the common case of /investigate being invoked while still on the default branch after the last PR merged. The guard resolves the remote and default branch through scripts/git-safety-lib.sh — the same resolvers Phase 6 uses to push, so the two cannot disagree. See references/git-safety.md.

Step 5.1 — Commit

Study the repo's commit style and match it:

git log --oneline -20

Most projects use Conventional Commits (fix: <desc> (#N) / feat: <desc> (#N)) or free-form (Fix <desc> (#N) / Add <desc> (#N)). Whatever the style, the subject must reference the issue with (#N). Add a one-line body on why, not what, when useful.

Authorship rule. Check the active git identity:

git config user.email

If it is pmatos@igalia.com, commit messages and PR bodies must not mention Claude, AI, "co-authored-by Claude", or generation tooling. (This rule lives in the user's global CLAUDE.md and supersedes default behaviour.)

Stage only the changed files (avoid git add -A), then commit:

git add <files>
git commit -m "<message>"

If a pre-commit hook fails, fix the underlying issue and create a new commit — never --no-verify, never --amend over a failed hook.

Phase 6 — Push and open the PR

Push the branch, honoring any existing upstream instead of hardcoding origin:

scripts/push-branch.sh

It first-pushes with -u on the remote resolved by git-safety-lib.sh, or does a bare git push if the branch already has an upstream. This matters for fork workflows and repos whose only remote is not origin. See references/git-safety.md.

Open a PR with gh pr create. The body must contain a closing keyword so GitHub auto-closes the issue on merge — Closes #N, Fixes #N (preferred for bugs), or Resolves #N. Invoke via HEREDOC to preserve formatting:

gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary

- <1–3 bullets on what changed and why>

Fixes #<N>

## Test plan

- [ ] <discovered test command> — all passing
- [ ] <discovered lint command> — clean
- [ ] <discovered type-check command> — clean
- [ ] Manual repro confirms the bug is fixed   (bug workflow only)
- [ ] Tests written first and seen failing — or: skipped because <reason>
EOF
)"

Mirror the commit subject in the PR title (minus the (#N) suffix — GitHub adds the PR number). Return the PR URL to the user.

Phase 7 — Post-PR

1. Post a friendly pointer on the issue (GitHub also links it via the closing keyword):

   gh issue comment "$ISSUE" --body "Opened PR <URL> to address this. Will auto-close on merge."

2. Do not close the issue manually — let the merged PR close it via the keyword, so a rejected PR leaves the issue open without intervention.
3. Report the PR URL and the test-plan checklist to the user.

Supporting skills

Use if available in the active session; otherwise fall back to the per-step alternative:

• /pm-plan — deep, multi-phase planning for non-trivial bugs or features. Fallback: write the plan directly with TaskCreate.
• /grill-with-docs (or /grill-me) — interactive design stress-test for ambiguous feature decisions. Fallback: a short AskUserQuestion-driven design pass before implementation.
• /tdd — red-green-refactor loop; the default way to implement 4A.5 and 4B.4. Fallback: write the failing test, confirm it fails, then write the implementation, manually.

Failure modes (quick reference)

Each row points to the phase that owns the exact behaviour and message — no message is duplicated here, to keep the single source of truth in one place.