prompts

Author: tmelliottjr

pkg/github/__toolsnaps__/project_read.snap

@@ -3,7 +3,7 @@
     "title": "Read project information",
     "readOnlyHint": true
   },
-  "description": "Read operations for GitHub Projects V2.\n\nMethods: get_project, list_projects, get_project_field, list_project_fields, get_project_item, list_project_items\n\nUSAGE GUIDANCE (CRITICAL):\n1. list_project_fields MUST be called first to discover field IDs before requesting item field values.\n2. ALWAYS provide a well‑scoped 'query' when calling list_project_items. Omitting 'query' returns broad mixed results (issues + PRs) and is inefficient.\n3. Filter by content type explicitly: add 'is:issue' or 'is:pr' as a qualifier in your query.\n4. To retrieve field values for items, pass the discovered IDs via the 'fields' argument on EVERY paginated call; otherwise only titles are returned.\n5. PAGINATION: After every list_* call, inspect pageInfo.hasNextPage. If true, immediately call again with the same method, same query, same fields, and after=pageInfo.nextCursor. Repeat until hasNextPage=false. Do not change per_page mid sequence. Use 'before' only when navigating backwards (rare).\n6. Accumulate all pages before performing analysis or summarization; partial data leads to incorrect results.\n\nExamples of query usage:\n- query='state:open is:issue priority:p1'\n- query='is:pr status:\"In Review\" team-name:\"Backend Team\"'\n- query='is:issue sprint-name:\"Q1 Planning\" assignee:@me'\n- query='unblocks:*copilot* is:issue state:open'\n\nCombine space-separated qualifiers for logical AND; use commas inside a qualifier for OR (e.g., label:bug,critical).",
+  "description": "Read operations for GitHub Projects V2.\n\nMethods: get_project, list_projects, get_project_field, list_project_fields, get_project_item, list_project_items\n\nIMPORTANT DISTINCTION:\nProjects (list_projects) and Project Items (list_project_items) use DIFFERENT query intent patterns.\n\n1. Project queries (list_projects) target PROJECT METADATA ONLY (e.g. title, state, updated time). DO NOT use item-only qualifiers like 'is:issue', 'is:pr', labels, assignee, sprint-name, parent-issue, etc. Those belong to items.\n2. Item queries (list_project_items) target ISSUES or PULL REQUESTS inside a project. MUST specify content type using 'is:issue' or 'is:pr' unless the user explicitly wants a mixed set.\n\nUSAGE GUIDANCE (CRITICAL):\n1. Call list_project_fields BEFORE requesting item field values so you can supply correct field IDs in 'fields'.\n2. For list_projects: keep queries lightweight and focused (e.g. title:*roadmap* state:open). Avoid item-level qualifiers.\n3. For list_project_items: ALWAYS build a precise, multi-filter query mapping user intent (see examples below). Start with type filter if scope is issues or PRs.\n4. To retrieve field values for items, pass discovered field IDs via 'fields' on EVERY paginated call; otherwise only title metadata returns.\n5. Pagination: After any list_* call, if pageInfo.hasNextPage=true, immediately repeat with after=pageInfo.nextCursor (same method, query, fields, per_page) until false. Don't change per_page mid-stream.\n6. Aggregate ALL pages BEFORE summarizing or analyzing to avoid incomplete results.\n\nCOMMON PROJECT (list_projects) QUERY EXAMPLES:\n- title:*roadmap*\n- state:open title:*2025*\n- updated:>@today-30d state:open\n\nCOMMON PROJECT ITEM (list_project_items) QUERY EXAMPLES:\n- state:open is:issue priority:p1\n- is:pr status:\"In Review\" team-name:\"Backend Team\"\n- is:issue sprint-name:\"Q1 Planning\" assignee:@me\n- unblocks:*copilot* is:issue state:open\n\nLOGIC RULES (items): Space-separated qualifiers = AND; commas inside one qualifier = OR (label:bug,critical). Use leading '-' for negation ( -label:wontfix ).",
   "inputSchema": {
     "properties": {
       "after": {
@@ -62,7 +62,7 @@
         "type": "number"
       },
       "query": {
-        "description": "Query string to filter project items (highly recommended for list_project_items).\n\t\tCRITICAL: Always include this when calling list_project_items.\n\t\t\n\t\tlist_project_items instructions:\n\n\t\tDerive the query from the user's natural language intent BEFORE invoking the tool. Map phrases directly:\n\t\t- \"open issues\" =\u003e state:open is:issue\n\t\t- \"merged PRs\" =\u003e state:merged is:pr\n\t\t- \"assigned to me\" =\u003e assignee:@me is:issue\n\t\t- \"high priority bugs\" =\u003e state:open is:issue label:bug priority:high\n\t\t- \"review-ready PRs\" =\u003e is:pr status:\"Ready for Review\"\n\n\t\tContent Type:\n\t\t- Issues: is:issue\n\t\t- Pull requests: is:pr (or is:pull-request)\n\t\tWithout one you'll get mixed types.\n\n\t\tLogical Combination:\n\t\t- Space-separated qualifiers = AND\n\t\t- Commas inside a single qualifier = OR (label:bug,critical)\n\t\t- Negation with leading dash: -label:wontfix\n\n\t\tFormat Rules:\n\t\t- Qualifiers with spaces use hyphens: sprint-name, team-name, parent-issue\n\t\t- Values with spaces use quotes: sprint-name:\"Q1 Planning\" status:\"In Review\"\n\t\t- Single word values: no quotes (state:open priority:high)\n\n\t\tExamples:\n\t\t- state:open is:issue sprint-name:\"Q1 Planning\"\n\t\t- is:pr team-name:\"Backend Team\" status:\"In Review\"\n\t\t- parent-issue:\"github/repo#123\"\n\n\t\tCommon Filters:\n\t\tis:issue/pr state:open/closed/merged assignee:@me/username label:name status:value priority:p1 updated:\u003e@today-7d title:*text* -label:wontfix label:bug,critical priority:1..3 no:assignee has:label iteration:@current\n\n\t\tPagination:\n\t\tWhen pageInfo.hasNextPage=true, use after=nextCursor to request the next page. Keep query, fields, and per_page identical for every page. Repeat until pageInfo.hasNextPage=false.\n\t\t",
+        "description": "Query string (used ONLY with list_projects and list_project_items). REQUIRED for list_project_items; OPTIONAL but recommended for list_projects.\n\nDIFFERENT PATTERNS:\n1. list_projects (PROJECT METADATA):\n   - Scope: project title, state, update time.\n   - DO NOT use item-only qualifiers: is:issue, is:pr, assignee:, label:, sprint-name:, parent-issue: etc.\n   - Good examples:\n     - title:*roadmap*\n     - state:open title:*2025*\n     - updated:>@today-30d state:open\n\n2. list_project_items (ISSUES / PRs INSIDE A PROJECT):\n   - MUST map natural language intent into precise filters.\n   - Start with explicit type when user scope is clear:\n     - \"open issues\" => state:open is:issue\n     - \"merged PRs\" => state:merged is:pr\n     - \"assigned to me\" => assignee:@me is:issue\n     - \"high priority bugs\" => state:open is:issue label:bug priority:high\n     - \"review-ready PRs\" => is:pr status:\"Ready for Review\"\n   - If user asks for \"items\" without specifying type, you may omit is:issue/is:pr OR ask for clarification.\n\nQUERY SYNTAX (items):\n   - Content type: is:issue | is:pr (or is:pull-request)\n   - AND: space-separated qualifiers.\n   - OR within one qualifier: label:bug,critical\n   - NOT: -label:wontfix\n   - Hyphenate multi-word field names: sprint-name, team-name, parent-issue\n   - Quote multi-word values: sprint-name:\"Q1 Planning\" status:\"In Review\"\n   - Unquoted single-word values: state:open priority:high\n\nExamples (items):\n   - state:open is:issue sprint-name:\"Q1 Planning\"\n   - is:pr team-name:\"Backend Team\" status:\"In Review\"\n   - parent-issue:\"github/repo#123\"\n\nCommon Filters (items):\n   is:issue|is:pr state:open|closed|merged assignee:@me|username label:NAME status:VALUE priority:p1 updated:>@today-7d title:*text* -label:wontfix label:bug,critical priority:1..3 no:assignee has:label iteration:@current\n\n⚠️ Use the USER'S phrasing to select correct field names (e.g. distinguish label vs single-select field).\n\nPAGINATION: When pageInfo.hasNextPage=true, call again with after=<nextCursor> using identical query, fields, per_page until false.",
         "type": "string"
       }
     },