feat(issue_graph): Add focus parameter, cross-repo support, and status extraction

- Add 'focus' parameter to shift focus to parent epic/batch
- Support cross-repo sub-issues and parent lookup via GraphQL
- Extract status updates from issue body, comments, and milestones
- Add state reason (completed, not_planned, duplicate, merged)
- Fetch project info for focus node
- Parse full GitHub URLs for cross-repo references
- Recognize GitHub Issue Types (Epic) for node classification
- Enhanced tool description to emphasize using issue_graph first
- Update issue_read description to defer to issue_graph for status
- Update server instructions with comprehensive issue_graph guidance

Author: SamMorrowDrums

README.md

@@ -718,6 +718,7 @@ The following sets of tools are available:
   - `repo`: Repository name (string, required)
 
 - **issue_graph** - Get issue relationship graph
+  - `focus`: Which node type to focus on: 'provided' (default) uses the specified issue/PR, 'epic' shifts focus to the nearest epic in the hierarchy, 'batch' shifts focus to the nearest batch/parent issue (string, optional)
   - `issue_number`: Issue or pull request number to build the graph from (number, required)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)

pkg/github/__toolsnaps__/issue_graph.snap

@@ -3,9 +3,18 @@
     "title": "Get issue relationship graph",
     "readOnlyHint": true
   },
-  "description": "Get a graph representation of an issue or pull request and its related issues/PRs.\n\nThis tool helps understand the relationships between issues and PRs in a repository, especially useful for:\n- Understanding the scope of work for an issue or PR\n- Planning implementation for a task that's part of a larger epic\n- Identifying blockers or dependencies\n- Finding related work that might conflict or overlap\n- Understanding why a piece of work exists (tracing to parent epic)\n\nThe graph shows:\n- Node types: epic (large initiatives), batch (parent issues), task (regular issues), pr (pull requests)\n- Parent/child relationships from sub-issues and \"closes/fixes\" references\n- Related issues mentioned in bodies\n\nCall this tool early when working on an issue to gather appropriate context about the work hierarchy.",
+  "description": "**PRIMARY TOOL FOR ISSUE/PR/PROJECT STATUS** - Returns the entire work hierarchy in ONE call. Use this FIRST before issue_read or other tools.\n\nFASTEST PATH TO PROJECT STATUS: One call returns all related issues, PRs, and their states - no need for multiple API calls.\n\nMUST USE THIS TOOL FIRST WHEN USER ASKS:\n- \"update on...\" / \"status of...\" / \"progress on...\" / \"tell me about...\"\n- \"what's happening with...\" / \"how is... going\" / \"state of...\"\n- \"project status\" / \"overall progress\" / \"how is the epic going\"\n- \"epic\" / \"parent issue\" / \"sub-issues\" / \"blocking\" / \"depends on\"\n- ANY request for status on work that might span multiple issues\n\nDO NOT use issue_read or list_issues first for status questions - issue_graph returns everything in one call.\n\nReturns a comprehensive view including:\n- Node types: epic (large initiatives), batch (parent issues), task (regular issues), pr (pull requests)\n- Full hierarchy: epic → batch → task → PR relationships across the ENTIRE project\n- Sub-issues and \"closes/fixes\" references\n- Cross-references and related work\n- Status updates extracted from issue bodies and comments\n- Open/closed/merged state of ALL related items\n\nUse focus=\"epic\" to automatically find and focus on the parent epic of any issue.",
   "inputSchema": {
     "properties": {
+      "focus": {
+        "description": "Which node type to focus on: 'provided' (default) uses the specified issue/PR, 'epic' shifts focus to the nearest epic in the hierarchy, 'batch' shifts focus to the nearest batch/parent issue",
+        "enum": [
+          "provided",
+          "epic",
+          "batch"
+        ],
+        "type": "string"
+      },
       "issue_number": {
         "description": "Issue or pull request number to build the graph from",
         "type": "number"

pkg/github/__toolsnaps__/issue_read.snap

@@ -3,7 +3,7 @@
     "title": "Get issue details",
     "readOnlyHint": true
   },
-  "description": "Get information about a specific issue in a GitHub repository.",
+  "description": "Get detailed information about a single issue: full body, comments, sub-issues, or labels.\n\n**USE issue_graph INSTEAD when user asks about:**\n- Status, updates, or progress on issues/PRs/epics\n- Project overview or how work is going\n- Parent issues, sub-issues, or work hierarchy\n- Related or blocking issues\n\nissue_read is for: reading the full issue body, fetching comments, listing sub-issues of a known parent, or getting label details - AFTER you already know which specific issue you need.",
   "inputSchema": {
     "properties": {
       "issue_number": {

pkg/github/instructions.go

@@ -63,9 +63,37 @@ Before creating a pull request, search for pull request templates in the reposit
 	case "issues":
 		return `## Issues
 
-Check 'list_issue_types' first for organizations to use proper issue types. Use 'search_issues' before creating new issues to avoid duplicates. Always set 'state_reason' when closing issues.
+**CRITICAL: For ANY question about issue/PR/epic status, updates, or progress - ALWAYS call 'issue_graph' FIRST before any other tool.**
 
-Use 'issue_graph' early when working on an issue to understand its context, hierarchy (epic → batch → task → PR), and related work. After identifying important issues in the graph, use 'issue_read' to get full details of specific issues.`
+'issue_graph' is the FASTEST PATH to project status - one call returns the entire work hierarchy (epic → batches → tasks → PRs) instead of multiple separate API calls.
+
+Trigger phrases that REQUIRE 'issue_graph' as the FIRST tool call:
+- "update on..." / "status of..." / "progress on..." / "tell me about..."
+- "what's happening with..." / "how is... going" / "state of..."
+- "project status" / "how is the project going" / "overall progress"
+- "epic" / "parent issue" / "sub-issues" / "blocking" / "depends on"
+- ANY issue/PR number reference when asking for status or updates
+
+Example: User asks "give me an update on issue #123" → Call issue_graph(owner, repo, 123) FIRST.
+Example: User asks "what's the status of the project" → Call issue_graph with the epic/tracking issue number.
+
+The 'issue_graph' tool returns in ONE call:
+- Full hierarchy: epic → batch → task → PR relationships across the entire project
+- All sub-issues and "closes/fixes" references  
+- Status updates extracted from issue bodies/comments
+- Cross-references and related work
+- Open/closed state of all related items
+
+Use focus="epic" to automatically find and focus on the parent epic of any issue.
+
+ONLY AFTER calling 'issue_graph', use other tools:
+- 'issue_read' for full details of specific issues identified in the graph
+- 'search_issues' to find related issues not in the graph
+
+For creating/modifying issues:
+- Check 'list_issue_types' first for organizations to use proper issue types
+- Use 'search_issues' before creating new issues to avoid duplicates
+- Always set 'state_reason' when closing issues`
 	case "discussions":
 		return `## Discussions