mach12:gh-issue-read

Read GitHub Issue

Goals

• Return the caller an authoritative issue snapshot containing the parent metadata and complete chronological comment stream.
• When requested, identify the most recent matching marker comment and its numeric ID without weakening completeness checks.
• Make incomplete or malformed history explicit rather than presenting partial evidence as authoritative.

This subroutine is gh-specific. A future forge-agnostic command set would substitute an equivalent glab-issue-read (or similar); the marker-hunt logic stays the same.

Step 1: Parse input

Extract:

• The issue number (required, first token).
• An optional --marker <html-marker> flag naming an HTML comment marker to locate (e.g., --marker mach12-plan, --marker mach12-decisions).

If no issue number is present, return an error to the caller and stop.

Step 2: Read the issue and complete comment stream

Resolve the canonical owner/name with gh repo view --json nameWithOwner. Query the issue through gh api graphql --paginate with explicit variables for owner, name, issue number, and $endCursor. Request parent title, body, createdAt, updatedAt, and:

comments(first: 100, after: $endCursor) {
  totalCount
  nodes { databaseId body author { login } authorAssociation createdAt url }
  pageInfo { hasNextPage endCursor }
}

The query must declare $endCursor: String and pass pageInfo.hasNextPage plus pageInfo.endCursor so --paginate follows every page. Accumulate comment nodes in chronological page order. Verify the accumulated node count exactly equals totalCount; reject duplicate database IDs. If pagination stops early, a page is malformed, the count differs, or any command fails, surface the full error and report that authoritative history is incomplete; do not return a partial array as complete. The caller decides whether the workflow can proceed without the issue.

Step 3: Locate the marker comment (if requested)