- "description": "Read operations for GitHub Projects.\n\nDECISION GUIDE (choose method):\n- get_project: You have a project number; you need its metadata.\n- list_projects: User wants to discover or filter projects (TITLE / OPEN STATE ONLY).\n- get_project_field: You know a field_id and need its definition.\n- list_project_fields: MUST call before fetching item field values (get IDs \u0026 types).\n- get_project_item: You have an item_id (project item) and want its details.\n- list_project_items: User wants issues/PRs inside a project filtered by criteria.\n\nINTENT TOKENS (map user phrasing → method):\n[INTENT:DISCOVER_PROJECTS] → list_projects\n[INTENT:INSPECT_PROJECT] → get_project\n[INTENT:ENUM_FIELDS] → list_project_fields\n[INTENT:FIELD_DETAILS] → get_project_field\n[INTENT:LIST_ITEMS] → list_project_items\n[INTENT:ITEM_DETAILS] → get_project_item\n\nCRITICAL DISTINCTION:\nProjects ≠ Project Items.\n- list_projects filters ONLY project metadata (title, open/closed).\n DO NOT use item-level qualifiers (is:issue, is:pr, assignee:, label:, status:, parent-issue:, sprint-name:, etc).\n- list_project_items filters ISSUES or PRs inside ONE project. Strongly prefer explicit type: is:issue OR is:pr unless user requests a mixed set.\n\nFAILURE MODES TO AVOID:\n1. Missing pagination (stops early) → ALWAYS loop while pageInfo.hasNextPage=true.\n2. Missing 'fields' when listing items → only title returned; no field values.\n3. Using item filters in list_projects → returns zero or irrelevant results.\n4. Ambiguous item type (issues vs PRs) → default to clarifying OR supply both (omit type only if user truly wants both).\n5. Inventing field IDs → fetch via list_project_fields first.\n6. INVENTING FIELD NAMES (NEW) → MUST use exact names returned by list_project_fields (case-insensitive match, preserve original spelling/hyphenation).\n\nFIELD NAME RESOLUTION (CRITICAL – ALWAYS DO BEFORE BUILDING QUERY WITH CUSTOM FIELDS):\n1. Call list_project_fields → build a map of lowercased field name → original field name + type.\n2. When user mentions a concept (e.g. \"current sprint\", \"this iteration\", \"in the cycle\"):\n - Identify iteration-type fields (type == iteration).\n - Accept synonyms in user phrasing: sprint, iteration, cycle.\n - If user uses a generic phrase (\"current sprint\") and the existing iteration field is named \"Sprint\" → use sprint:@current.\n - If the field is named \"Cycle\" → cycle:@current.\n - If the field is named \"Iteration\" → iteration:@current.\n - NEVER substitute a synonym that does not exist among field names.\n3. For any other custom fields (e.g. \"dev phase\", \"story points\", \"team name\"):\n - Normalize user phrase → lower-case, replace spaces with hyphens.\n - Match against available field names in lower-case.\n - Use the ORIGINAL field name in the query exactly (including hyphenation and case if needed).\n4. If multiple iteration-type fields exist and the user intent is ambiguous → ask for clarification OR pick the one whose name best matches the user phrase.\n5. INVALID if you use a field name not present in list_project_fields.\n\nVALID vs INVALID (Iteration Example):\nUser request: \"Analyze the last week's activity ... for issues in the current sprint\"\nFields contain iteration field named \"sprint\":\n VALID: is:issue updated:\u003e@today-7d sprint:@current\n INVALID: is:issue updated:\u003e@today-7d iteration:@current\nFields contain iteration field named \"cycle\":\n VALID: is:issue updated:\u003e@today-7d cycle:@current\n INVALID: is:issue updated:\u003e@today-7d iteration:@current\nFields contain iteration field named \"iteration\":\n VALID: is:issue updated:\u003e@today-7d iteration:@current\n INVALID: is:issue updated:\u003e@today-7d sprint:@current (if 'sprint' not defined)\n\nIf NO iteration-type field exists → omit that qualifier OR clarify with user (\"No iteration field found; continue without sprint filter?\").\n\nQUERY TRANSLATION (items):\nUser: \"Open sprint issues assigned to me\" →\n state:open is:issue assignee:@me sprint:@current\nUser: \"PRs waiting for review\" →\n is:pr status:\"Ready for Review\"\nUser: \"High priority bugs updated this week\" →\n is:issue label:bug priority:high updated:\u003e@today-7d\n\nSYNTAX RULES (items):\n- AND: space-separated qualifiers.\n- OR: comma inside one qualifier (label:bug,critical).\n- NOT: prefix qualifier with '-' (-label:wontfix).\n- Hyphenate multi-word field names: sprint-name, team-name, parent-issue.\n- Quote multi-word values: status:\"In Review\".\n- Comparison \u0026 ranges: priority:1..3 updated:\u003c@today-14d.\n- Wildcards: title:*search*, label:bug*.\n- Presence: has:assignee, no:label, -no:assignee (force presence).\n\nGOOD PROJECT QUERIES (list_projects):\n roadmap is:open\n is:open feature planning\nBAD (reject for list_projects — item filters present):\n is:issue state:open\n assignee:@me sprint-name:\"Q3\"\n label:bug priority:high\n\nVALID ITEM QUERIES (list_project_items):\n state:open is:issue priority:high sprint:@current\n is:pr status:\"In Review\" team-name:\"Backend Team\"\n is:issue -label:wontfix updated:\u003e@today-30d\n is:issue parent-issue:\"github/repo#123\"\n\nPAGINATION LOOP (ALL list_*):\n1. Call list_*.\n2. Read pageInfo.hasNextPage.\n3. If true → call again with after=pageInfo.nextCursor (same query, fields, per_page).\n4. Repeat until hasNextPage=false.\n5. Aggregate ALL pages BEFORE summarizing.\n\nDATA COMPLETENESS RULE:\nNever summarize, infer trends, or perform counts until all pages are retrieved.\n\nDEEP DETAILS:\nProject item = lightweight wrapper. For full issue/PR inspection use issue_read or pull_request_read after enumerating items.\n\nDO:\n- Normalize user intent → precise filters.\n- Fetch fields first → pass IDs every page.\n- Preserve consistency across pagination.\n- Resolve and validate field names from list_project_fields BEFORE using them.\n\nDON'T:\n- Mix project-only and item-only filters.\n- Omit type when user scope is explicit.\n- Invent field IDs or option IDs.\n- Invent field names (e.g. use iteration:@current when only sprint exists).\n- Stop early on pagination.",
0 commit comments