gwt-issue-search

name

gwt-issue-search

description

Semantic search over all GitHub Issues using vector embeddings. Use when searching for existing issues, finding related issues, checking for duplicate issues, or determining which issue owns a scope. Mandatory preflight before gwt-register-issue, gwt-fix-issue, and visible SPEC routing decisions. Use when user says 'search issues', 'find related issues', 'check for duplicates', or asks which issue owns a scope.

Issue Search

gwt maintains a vector search index of GitHub Issues using ChromaDB embeddings (model: intfloat/multilingual-e5-base). The index is stored at ~/.gwt/index/<repo-hash>/issues/ and is Worktree-independent. The gwt GUI app (WebView built with wry + tao + axum WebSocket and xterm.js) refreshes it asynchronously at startup with a 15-minute TTL; external runner invocations get an auto-build on the first search.

gwtd resolution

Before executing any gwtd ... command from this skill or its references, resolve GWT_BIN first: executable GWT_BIN_PATH, then command -v gwtd, then $GWT_PROJECT_ROOT/target/debug/gwtd or ./target/debug/gwtd. Run the command as "$GWT_BIN" ...; if none exists, stop with an actionable gwtd not found error.

Issues search first

When the user asks any of the following, use GitHub Issues search before manual gwtd issue view, title grep, or file search:

• "既存 Issue を探して"
• "関連 Issue を探して"
• "Project Index の統合仕様を確認して"
• "bug / feature の過去設計を見たい"

Minimum workflow:

1. Run search-issues with 2-3 semantic queries derived from the request (the runner auto-builds the index if missing)
2. Pick the canonical existing issue if found
3. Only fall back to creating a new issue when no suitable canonical issue exists

Suggested query patterns:

• subsystem + purpose
  • project index issue search spec
• user-facing problem + architecture term
  • chroma persisted db recovery project index
• workflow / discoverability requirement
  • LLM should use gwt-issue-search before spec creation

Environment

When the gwt GUI app launches an agent pane, the following env vars are exported automatically:

• GWT_PROJECT_ROOT — absolute path of the active worktree
• GWT_REPO_HASH — SHA256[:16] of the normalized origin URL

GWT_REPO_HASH is an optimization, not a requirement: when it is unset or passed empty, the runner derives it from --project-root automatically (Issue #2933). A search therefore needs only --project-root, and works in any shell on any platform.

GitHub Issues search command

~/.gwt/runtime/chroma-venv/bin/python3 ~/.gwt/runtime/chroma_index_runner.py \
  --action search-issues \
  --repo-hash "$GWT_REPO_HASH" \
  --project-root "$GWT_PROJECT_ROOT" \
  --query "your search query" \
  --n-results 10

If the Issue index does not yet exist, the runner builds it inline (full mode) by refreshing issue data and embedding the results, then performs the search.

To force a refresh ignoring TTL:

~/.gwt/runtime/chroma-venv/bin/python3 ~/.gwt/runtime/chroma_index_runner.py \
  --action index-issues \
  --repo-hash "$GWT_REPO_HASH" \
  --project-root "$GWT_PROJECT_ROOT"

Add --respect-ttl to skip when the previous refresh is younger than 15 minutes (used by the gwt GUI startup background task).

Issues search output format

{"ok": true, "issueResults": [
  {"number": 42, "title": "Add vector search for Issues", "url": "https://github.com/...", "state": "open", "labels": ["enhancement"], "distance": 0.08}
]}

When to use

• Issue lookup: find existing GitHub Issues before creating new ones
• Task start: search for Issues related to the assigned feature
• Bug investigation: find Issues that might relate to the bug
• Feature addition: locate relevant Issues for similar implementations

Notes

• The gwt GUI app refreshes the Issue index automatically at startup (TTL 15 min). External runner invocations trigger an inline build on the first search.
• Uses semantic similarity (not just keyword matching)
• Lower distance values indicate higher relevance
• For SPEC search, use gwt-spec-search instead (SPECs are GitHub Issues cached at ~/.gwt/cache/issues/)
• For file search, use gwt-project-search instead