project-management

# Project Management for dotnet/msbuild This skill covers everything you need to manage issues and the project board for the MSBuild repository: querying, commenting, editing, creating issues, and bulk operations on the project board (sprints, status, assignees, etc.). ## Where things live - **Repository:** `dotnet/msbuild` — all issues, PRs, and discussions. - **Project board:** [`dotnet/projects/117`](https://github.com/orgs/dotnet/projects/117) — title "MSBuild". This is the canonical project board for the team. Most issues created in `dotnet/msbuild` are auto-added or manually added here for sprint planning. - **Sprints** are tracked via the **Sprint** iteration field on project 117. Iteration titles use the format `2026 May I`, `2026 May II`, `2026 June I`, etc. (roughly two-week iterations). > Note: there are/were other auxiliary project boards for specific initiatives. Use project 117 unless the user explicitly points at another one. ### Stable identifiers for project 117 | Identifier | Value | |---|---| | Project node ID | `PVT_kwDOAIt-yc4ABM5F` | | Sprint field ID (iteration) | `PVTIF_lADOAIt-yc4ABM5FzgAtMGI` | These IDs are stable but can be re-derived if the project is ever recreated or migrated: ```bash # Project node ID gh api graphql -f query='{ organization(login:"dotnet") { projectV2(number:117) { id } } }' # All field IDs (Sprint, Status, Area, Priority, …) gh project field-list 117 --owner dotnet --format json | jq '.fields[] | {id,name,type}' ``` ## Tooling preference For GitHub work, prefer `gh` CLI over MCP tools (per repo convention). - Use `gh issue ...` for issue-level operations (create / view / comment / edit / close). - Use `gh project ...` for project-board CRUD. - Use `gh api graphql` for anything `gh` doesn't expose directly (sprint values per item, project-level field values, bulk reads). The default `gh` token may not include the `project` scope. If a `gh project ...` write call fails with a scope error, ask the user to run: ```bash gh auth refresh -s project ``` ## Common single-issue actions ```bash # View gh issue view 13315 --repo dotnet/msbuild --json title,body,state,assignees,labels # Comment (use --body-file to avoid shell-quoting traps with multi-line markdown) gh issue comment 13315 --repo dotnet/msbuild --body-file ./comment.md # Amend body (overwrite — there is no append; use view → edit → write) gh issue edit 13597 --repo dotnet/msbuild --body-file ./new-body.md # Create gh issue create --repo dotnet/msbuild --title "Title" --body-file ./body.md # Add labels / assignees gh issue edit 13315 --repo dotnet/msbuild --add-label "Area: Server" --add-assignee someuser ``` When drafting comments / bodies that summarize internal discussions: - Use neutral, team-voice language ("the team agreed", "open question"). - Scrub names, "X said Y", room/agent identifiers, and anything resembling internal politics. - Always write to a file and use `--body-file`. Don't try to inline multi-line markdown. ## Querying issue → project field values (sprint, status, project-level assignees) `gh issue view` does **not** return project-board field values. Use GraphQL via the `repository → issue → projectItems` path: ```bash gh api graphql -f query=' query { r: repository(owner:"dotnet", name:"msbuild") { issue(number: 13315) { id projectItems(first: 5) { nodes { id project { number title } sprint: fieldValueByName(name: "Sprint") { ... on ProjectV2ItemFieldIterationValue { title iterationId } } status: fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name optionId } } } } } } }' ``` > `fieldValueByName` returns `null` when the field has no value set on that item — handle accordingly. ## Bulk / board-wide queries The `gh project item-list` CLI command has internal limits and is unreliable for large boards (project 117 is in the thousands of items). **Use GraphQL with pagination.** ```python import subprocess, json PROJECT_NUMBER = 117 ORG = "dotnet" results = [] cursor = None while True: after = f', after: "{cursor}"' if cursor else '' query = f'''query {{ organization(login: "{ORG}") {{ projectV2(number: {PROJECT_NUMBER}) {{ items(first: 100{after}) {{ pageInfo {{ hasNextPage endCursor }} nodes {{ id fieldValues(first: 20) {{ nodes {{ ... on ProjectV2ItemFieldIterationValue {{ field {{ ... on ProjectV2IterationField {{ name }} }} title }} ... on ProjectV2ItemFieldUserValue {{ field {{ ... on ProjectV2Field {{ name }} }} users(first: 10) {{ nodes {{ login }} }} }} ... on ProjectV2ItemFieldSingleSelectValue {{ field {{ ... on ProjectV2SingleSelectField {{ name }} }} name }} }} }} content {{ ... on Issue {{ number title }} ... on PullRequest {{ number title }} ... on DraftIssue {{ title }} }} }} }} }} }} }}''' try: r = subprocess.run(['gh','api','graphql','-f',f'query={query}'], capture_output=True, text=True, check=True) except subprocess.CalledProcessError as e: raise RuntimeError(f"GraphQL query failed: {e.stderr}") from e page = json.loads(r.stdout)['data']['organization']['projectV2']['items'] for node in page['nodes']: sprint = status = None assignees = [] for fv in node.get('fieldValues', {}).get('nodes', []): if not fv: # null entries for unset fields continue fname = (fv.get('field') or {}).get('name', '') if fname == 'Sprint': sprint = fv.get('title') elif fname == 'Status': status = fv.get('name') elif fname == 'Assignees': assignees = [u['login'] for u in (fv.get('users') or {}).get('nodes', [])] results.append({'id': node['id'], 'sprint': sprint, 'status': status, 'assignees': assignees, 'content': node.get('content')}) if not page['pageInfo']['hasNextPage']: break cursor = page['pageInfo']['endCursor'] ``` ## Updating project-board field values ### Set a sprint (iteration) — first look up iteration IDs Iteration IDs are short hex strings (e.g., `303c2425`). They are **not** the same across projects; always look them up from project 117. ```bash gh api graphql -f query=' query { node(id: "PVTIF_lADOAIt-yc4ABM5FzgAtMGI") { ... on ProjectV2IterationField { configuration { iterations { id title startDate } completedIterations { id title startDate } } } } }' | jq '.data.node.configuration | (.iterations + .completedIterations)[] | {id,title}' ``` ### Single-item field update — `gh project item-edit` ```bash # Iteration / sprint gh project item-edit \ --project-id PVT_kwDOAIt-yc4ABM5F \ --id <PROJECT_ITEM_ID> \ --field-id PVTIF_lADOAIt-yc4ABM5FzgAtMGI \ --iteration-id <ITERATION_ID> # Single-select (Status, Area, Priority): use --single-select-option-id # Text: --text | Number: --number | Date: --date YYYY-MM-DD ``` ### Single-item field update — GraphQL mutation (works the same) ```bash gh api graphql -f query=' mutation { updateProjectV2ItemFieldValue(input: { projectId: "PVT_kwDOAIt-yc4ABM5F", itemId: "<PROJECT_ITEM_ID>", fieldId: "PVTIF_lADOAIt-yc4ABM5FzgAtMGI", value: { iterationId: "<ITERATION_ID>" } }) { projectV2Item { id } } }' ``` ### Adding a freshly created issue to project 117 A newly-created issue is not always auto-added. To add and set its sprint: ```bash ISSUE_NODE_ID=$(gh api graphql -f query=' query { repository(owner:"dotnet",name:"msbuild") { issue(number:13707) { id } } }' \ | jq -r '.data.repository.issue.id') ITEM_ID=$(gh api graphql -f query=' mutation { addProjectV2ItemById(input:{ projectId:"PVT_kwDOAIt-yc4ABM5F", contentId:"'"$ISSUE_NODE_ID"'" }) { item { id } } }' | jq -r '.data.addProjectV2ItemById.item.id') gh api graphql -f query=' mutation { updateProjectV2ItemFieldValue(input:{ projectId:"PVT_kwDOAIt-yc4ABM5F", itemId:"'"$ITEM_ID"'", fieldId:"PVTIF_lADOAIt-yc4ABM5FzgAtMGI", value:{iterationId:"<ITERATION_ID>"} }) { projectV2Item { id } } }' ``` ## Common errors and gotchas ### 1. `Field 'fieldValueByName' has an argument conflict` `gh api graphql --paginate` (and several jq-style aliases) re-uses field names. If you call `fieldValueByName(name:"Sprint")` and `fieldValueByName(name:"Status")` in the same selection set without aliases, you'll get: ``` Field 'fieldValueByName' has an argument conflict: {name:"Sprint"} or {name:"Status"}? ``` Fix: alias each call. ```graphql sprint: fieldValueByName(name: "Sprint") { ... } status: fieldValueByName(name: "Status") { ... } ``` ### 2. `gh api graphql --paginate` produces concatenated JSON, not one document Each page is emitted as a separate JSON object on stdout; piping straight into `jq` fails with "Invalid numeric literal". Either: - paginate manually in a loop (preferred for large reads), or - use `jq --slurp` to read the stream as an array. ### 3. "Selections can't be made directly on unions" `field` on a project field value is a union; you can't select `name` directly. Use a typed inline fragment per concrete field type (`ProjectV2Field`, `ProjectV2IterationField`, `ProjectV2SingleSelectField`, …). ### 4. Issue-level assignees ≠ project-board "Assignees" column The board's "No Assignees" slice is driven by the **project-level Assignees field**, not by `Issue.assignees`. They can diverge. When filtering by board state, always read `ProjectV2ItemFieldUserValue` from `fieldValues`. ### 5. `null` entries in `fieldValues.nodes` GraphQL returns `null` for items where a particular field is unset. Always guard `if not fv: continue` before dereferencing. ### 6. DraftIssue items lack `number` / `repository` `content` may be a `DraftIssue` that only exposes `title`, `body`, `assignees`. Code that joins to issue numbers must handle `None`. ### 7. `gh project item-list` is unreliable for large boards It silently truncates. Always use the GraphQL pagination loop above instead. ### 8. Missing `project` scope on `gh` token Reads work; writes (`gh project item-edit`, the `addProjectV2ItemById` / `updateProjectV2ItemFieldValue` mutations) fail. Have the user run `gh auth refresh -s project`. ### 9. `gh issue edit --body` overwrites — there is no append To "append" to a body, fetch with `gh issue view --json body`, append, write back with `--body-file`. For status updates, prefer a comment. ## Sanitization checklist for comments / body edits When summarizing meetings or chat threads into GitHub: - ✅ Use team voice ("the team agreed", "open question", "follow-up needed"). - ✅ Keep objective, decision-relevant content (problem statement, scope, exit criteria, repro steps, numbers). - ❌ No personal names or "X said / Y replied". - ❌ No full email addresses of external contributors (use GitHub handles instead). - ❌ No internal-only identifiers (room names, recording IDs, agent fleet identifiers, partner-team contractor names). - ❌ No speculation about other teams' motives or anything resembling internal politics. - ❌ No confidential roadmap dates or unreleased product details unless already public. - Always show the user the proposed comment / body before posting (unless they've explicitly preapproved). ## Common workflows | Goal | Sketch | |---|---| | Add a status comment to N issues | `for n in 13315 13702 …; do gh issue comment $n --repo dotnet/msbuild --body-file ./c-$n.md; done` | | Replace a one-line issue body with a full Context / Exit-criteria / Out-of-scope spec | `gh issue edit <n> --repo dotnet/msbuild --body-file ./body.md` | | Move all unassigned items from sprint X to sprint Y | GraphQL pagination loop above + `gh project item-edit --iteration-id` per item | | File a new issue and put it in the current sprint | `gh issue create` → `addProjectV2ItemById` → `updateProjectV2ItemFieldValue` | | Audit "what's in the current sprint that has no owner" | GraphQL pagination loop, filter on `Sprint == "<current>"` and empty `Assignees` |