triage

name	triage
description	Work-unit triage for GitHub issues. Groups raw issues, fuses each group with the AGENTS.md northstar, and externalizes each routed unit to a substrate record a collaborator session is pointed at.

Triage: Work-Unit Formation

Form executable work units from GitHub issue substrate, handing execution — branches, PRs, applied fixes — to a normal session. It reads raw issues, groups related issues, fuses each group with the project's inscribed northstar and the user's current-session judgment, forms one or more focused work units, and — once the user routes a unit for handoff — externalizes it to a substrate-owned record a continuing collaborator session is pointed at.

Core Contract

/triage owns work-unit formation:

BacklogIntake
  -> RawIssueSet
  -> IssueGroup
  -> NormalizedProblemFrame
  -> NorthstarFusion
  -> FocusedWorkUnit
  -> RouteChoice
       -> independent session: externalize -> WorkUnitRecord
       -> re-triage: back to the relevant earlier phase, no record externalized

Execution is not /triage's. The receiving session starts from the record's canonical locator, dereferences the work-unit record with its own tools, grounds the premises it needs, and does the branching, editing, and PR work itself as a continuing collaborator, not a mere executor. Arranging how several routed units run is likewise outside this skill: /triage externalizes one record per routed unit and stops.

Types

Type	Meaning
BacklogIntake	The scale-aware intake step that binds an explicit issue scope or, when no scope is supplied, inspects the current repository's open GitHub issue backlog through lightweight metadata before deciding how much substrate to read. Scale is judged by triage load, not by a fixed issue-count threshold.
RawIssueSet	The issue substrate read from GitHub: issue body, comments, labels, linked PRs, and explicitly cited blockers. Scope this narrowly to issues; do not call it external signals.
IntakeIntent	The user-recognized purpose for the triage pass, explicitly stated in the current session.
TriageLoad	A metadata-grounded composite judgment spanning IssueLoad, RepoLoad, MappingLoad, and IntentAmbiguity.
IssueGroup	One or more raw issues that share a problem pressure: similar symptom, target behavior, conceptual request, affected surface, or blocked execution axis.
NormalizedProblemFrame	A single problem statement reconstructed from the issue group, with duplicates collapsed and contradictions surfaced.
Northstar	The inscribed direction line read from AGENTS.md or the active project guide, usually under ## Northstar. This may have been produced by /realign.
NorthstarFusion	A session-text trace showing how the normalized problem frame preserves, transforms, or drops issue claims in light of the northstar and the user's current judgment.
FocusedWorkUnit	The executable unit formed from one issue group after northstar fusion. Default cardinality is IssueGroup -> FocusedWorkUnit one-to-one. Split only when northstar fusion exposes distinct execution axes.
RouteChoice	The user's current-session choice for a formed work unit: hand it off to an independent session, or re-triage it.
WorkUnitRecord	The substrate-owned record a routed FocusedWorkUnit is externalized to — an anchor-issue comment or issue-body triage section carrying the problem frame, fusion trace, issue provenance, exclusions, and verification expectations. It is the canonical record; the receiving session dereferences it rather than a session-local restatement of it.

Phase 0: Bind Scope

Accept one of:

• Explicit issue numbers or URLs
• A GitHub query scope such as a label, milestone, project view, or gh issue list filter
• The current session's issue set if the user has already surfaced raw issues
• A user-supplied issue list pasted into the session

If no scope is recoverable, default to the current repository's open GitHub issue backlog. First perform a lightweight metadata pass, not a full substrate read:

gh issue list --state open --json number,title,labels,state,createdAt,updatedAt,assignees,milestone

If GitHub access is unavailable or the current repository cannot be identified, ask for the issue scope or pasted issue list.

Classify the intake scale by TriageLoad before reading full issue bodies and comments:

Load axis	Signals to inspect from metadata and repo shape
IssueLoad	Open issue volume relative to the next checkpoint, recent arrival rate, title/body preview density when available, comment/dependency/link indicators, unlabeled or stale proportion, duplicate / needs-info candidates.
RepoLoad	Repository surface area, number of independently deployable packages or runtime surfaces, verifier/test matrix breadth, known co-change requirements, ownership or component boundaries.
MappingLoad	How clearly issue titles/labels map to code, docs, runtime, verifier, or protocol surfaces; whether many issues span several surfaces or lack enough metadata to map.
IntentAmbiguity	Whether the current session has clarified the triage purpose: executable work selection, stale backlog reduction, milestone/release preparation, duplicate consolidation, blocker surfacing, or another explicit intent.

Use the load axes to choose an intake posture:

Posture	Intake path
Small	Full-scan the bound open issues into RawIssueSet, then group. Use this only when IssueLoad, RepoLoad, MappingLoad, and IntentAmbiguity are all low enough that full substrate reading fits the next checkpoint.
Medium	Build a metadata grouping map first. Surface candidate clusters in Phase 2 before the user confirms selection, then read full substrate only for confirmed clusters. Use this when full scan is plausible but one or more load axes would make silent reading too costly.
Large	Call /elicit to crystallize IntakeIntent, convert that intent into a GitHub query/filter or cluster selection, then read full substrate only for the resulting slice. Use this whenever full substrate reading would exceed the next checkpoint or the triage purpose is unclear.

If the user explicitly asks for a full-backlog audit on a medium or large backlog, process metadata in checkpointed batches and surface progress between batches. Defer full body/comment reads until after the first grouping checkpoint.

Load is not legible from labels. TriageLoad sizes the intake (how much substrate to read now). It does not measure the deliverable load a unit imposes downstream — the human judgment its execution and review will demand. These are independent: a refactor/enhancement label does not imply low deliverable load. An audit or candidate-classification issue — one whose output is a decision (which candidates to act on, merge-vs-keep, discriminant-vs-removable) — carries high deliverable load because it spawns in-session judgment gates, even when its surface reads as mechanical. When ordering or routing units by reviewer cost, read deliverable load from what the issue produces (a mechanical edit vs a decision), not from its type label.

Phase 1: Read Raw Issues

Read the full issue substrate for each issue in the bound scope or confirmed cluster:

• number, title, body, labels, state, author, timestamps
• comments that contain reporter answers, prior triage notes, review feedback, or maintainer decisions
• linked PRs and explicit references such as depends on #N
• labels or body sections indicating blocked, out-of-scope, stale, or ready states

Use the available GitHub interface (gh, MCP, or pasted issue text). Preserve issue numbers in every downstream artifact.

For medium and large intake postures, metadata-only lists are provisional. They can seed IssueGroup candidates, but a candidate cannot become a NormalizedProblemFrame, a FocusedWorkUnit, or an externalized WorkUnitRecord until the relevant full issue substrate has been read.

Phase 2: Group Issues

Propose IssueGroup candidates by problem pressure, not by label alone.

Useful grouping signals:

• same user-facing symptom or desired behavior
• same issue type, impact, urgency, severity, or priority pressure
• same component, owner, milestone, or affected runtime surface
• same protocol, skill, runtime surface, or verifier surface
• same missing decision or northstar tension
• same stale, blocked, duplicate, or needs-info disposition
• duplicate or near-duplicate requests
• one issue's proposed fix depends on another issue's premise

Labels can seed grouping, especially type / priority / severity / component labels, but they do not replace problem-pressure grouping.

Surface the grouping map before moving to fusion. If grouping is contested, present 2-3 grouping alternatives with their downstream work-unit shape. The user may confirm, adjust, split, merge, or ask for re-triage.

Phase 3: Normalize Problem Frames

For each confirmed IssueGroup, write a NormalizedProblemFrame:

• Problem: one sentence naming the shared pressure
• Included issues: issue numbers and one-line contribution from each
• Observed evidence: concise issue-body/comment evidence
• Conflicts or drift: contradictions, stale claims, or unresolved issue premises
• Missing context: specific facts needed before execution, if any
• Out of scope: nearby requests the group should not absorb

This is not an implementation plan. It is the issue group's shared problem frame.

Phase 4: Fuse With Northstar

Read the active project northstar from AGENTS.md, CLAUDE.md, or the project guide. Prefer AGENTS.md when present in Codex contexts.

For each NormalizedProblemFrame, produce a NorthstarFusion trace:

• Preserved: issue claims that directly serve the northstar
• Transformed: issue claims reframed by the northstar
• Dropped: issue claims that are unsupported, stale, or outside the current work unit
• User-session judgment: the current-session interpretation or route preference the user has expressed

The fusion happens in session text. GitHub may store the result later, but the user's route judgment is constituted in the Codex session.

Phase 5: Form Focused Work Units

Convert each fused frame into a FocusedWorkUnit.

Default rule: one confirmed IssueGroup becomes one FocusedWorkUnit.

Split the group only when:

• northstar fusion exposes separate execution axes
• one subset is blocked while another is ready
• one subset needs exploration before it can be framed while another is ready to hand off
• verification surfaces are disjoint enough that one PR would hide the review basis

Each work unit includes:

• name
• normalized problem frame
• northstar fusion trace
• included issues
• excluded issues or claims
• readiness status: ready, needs-info, blocked, stale, or split-required
• verification expectations
• suggested route with rationale

Phase 6: Route Choice

Present the work units and ask the user to choose a route for each:

1. Independent session — externalize this unit to a substrate record and point a fresh collaborator session at it.
2. Re-triage — revise grouping, fusion, or work-unit boundaries.

The route choice is the input Phase 7 consumes: a unit routed to an independent session proceeds to Phase 7. Re-triage returns to the relevant earlier phase; no record is externalized for that cycle.

Phase 7: Externalize and Point

For each work unit the user routed to an independent session, hand off in two steps: externalize the unit to a substrate-owned record, then hand the receiving session that record's locator rather than a restatement of its contents.

Externalize: write the work unit — its NormalizedProblemFrame, its NorthstarFusion trace, the included issue numbers with their per-issue contribution, exclusions, readiness, and verification expectations — to a substrate-owned record the receiving session will actually read: the WorkUnitRecord. Its natural home is the issue substrate the unit came from — an issue-body triage section on the unit's anchor issue first (the issue body is squarely inside the project's inscribed ledger convention), or an anchor-issue comment (the same git-hosted issue record; this project's own decision chains live in issue comments). The anchor issue is bound deterministically when the record home is chosen: the included issue whose problem statement the unit's NormalizedProblemFrame primarily derives from; when the frame does not single one out, the earliest-created included issue — a deterministic tiebreak, surfaced as a relay annotation alongside the externalization, so a multi-issue group never leaves the mutation target to a silent choice. The record is the canonical one; it, not session text, is what the receiving session dereferences. The grouping rationale, northstar fusion, and route intent travel IN the record as decision-shaped content, so the collaborator reads them at the source rather than in a second, unenforced restatement.

Point: hand the receiving session a navigation block over that record, per the project's session-handoff routing convention — purpose and frame, the record's canonical locator (the issue-comment URL or equivalent stable reference), the dereference instruction, a snapshot anchor where exact-state determinacy is needed, and the grounding instruction to verify load-bearing premises against current state and stop when a source is unreachable or a needed premise lacks support-integrity. Do not author a second copy of what the record already holds: /triage supplies purpose and entry point, and the recipient derives what to take from that purpose. The declared recipient Role is a continuing collaborator — one that inherits the triage judgment and carries the work forward as a full participant, not a mere executor — and method stays with the recipient.

Re-triage does not reach this phase: revising grouping, fusion, or work-unit boundaries externalizes no record.

The receiving session starts from that locator, dereferences the record with its own tools, and continues the work from the record itself.

Rules

1. Backlog intake default (Architectural — usable entrypoint): A bare /triage call defaults to the current repository's open GitHub issue backlog through a lightweight metadata pass. Ask for scope only when repository issue access is unavailable or ambiguous.
2. RawIssueSet scope (Architectural — substrate boundary): Use RawIssueSet, not broad external-signal language, for the issue substrate. The concrete input is GitHub issues or pasted issue equivalents.
3. Dynamic scale judgment (Architectural — bounded attention): Classify small, medium, or large by TriageLoad, not by a fixed issue-count threshold. Issue count is only one signal inside IssueLoad.
4. Scale-aware substrate read (Architectural — bounded attention): Small intake may be full-scanned; medium intake requires metadata-first cluster confirmation; large intake requires IntakeIntent via /elicit before full substrate reads.
5. Metadata is provisional (Architectural — substrate boundary): Metadata-only grouping cannot produce a work unit. Full issue substrate is required before normalization, northstar fusion, and handoff composition.
6. Work-unit formation, not execution (Architectural — role boundary): /triage does not edit production files, create implementation branches, open PRs, or apply fixes.
7. IssueGroup default cardinality (Architectural — review-surface visibility): Default to IssueGroup -> FocusedWorkUnit one-to-one. Split only with cited execution-axis evidence.
8. Northstar fusion required (Axiom anchor — Convergence Persistence): Every ready work unit includes a fusion trace against the active project northstar. A summary without fusion is not a triaged work unit.
9. Session route authority (Axiom anchor — Detection with Authority): Route choice belongs to the user in the current session. GitHub labels or project fields may record the choice but do not replace it.
10. Externalized record is the handoff artifact (Architectural — handoff specificity): A receiving session starts from a locator pointing at the externalized WorkUnitRecord — never a raw issue list, and never a session-local unit that was never written to substrate: every unit that crosses the session boundary goes through the Phase 7 externalize-then-point path.
11. No silent grouping (Derived — Surfacing over Deciding): Surface grouping candidates before forming work units. Similarity grouping is a user-recognized judgment, not a hidden classifier result.

Boundary Note

/triage reads GitHub issue substrate and emits focused work units. It may read the current northstar produced by /realign, but it does not rewrite the project guide. It externalizes routed work units to substrate records and points independent collaborator sessions at them, but does not execute branches, PRs, or review compliance, and does not arrange the order or concurrency in which several routed units run.

Composition

Triage composes the following protocols at runtime:

• Phase 0 (large intake posture): /elicit (Euporia) — crystallizes IntakeIntent before full substrate reads

Composition is sequential — each phase consumes the previous phase's output. The re-triage route at Phase 6 does not reach Phase 7; that cycle externalizes no record.

Phase 7's grounding instruction names /inquire as the receiving session's action, not a protocol /triage composes: the navigation block instructs the recipient to ground load-bearing premises, and the recipient realizes that instruction with whatever its own environment affords.

Anti-patterns

• Count-threshold scale: deciding small, medium, or large by a fixed issue count instead of TriageLoad.
• Unbounded backlog scan: reading full bodies/comments for a medium or large intake posture before a metadata grouping checkpoint or /elicit-formed IntakeIntent.
• Label-only grouping: labels can seed grouping, but the work unit must be formed by shared problem pressure and cited issue evidence.
• Label-implies-load: inferring low deliverable (execution/review) load from a refactor/mechanical label when the issue's output is a decision or candidate-classification that will spawn in-session judgment gates.
• Metadata-only work units: emitting normalized frames, focused work units, or composed handoffs from titles/labels alone.
• Northstar-free summary: a raw issue summary without preserved/transformed/dropped claims is not a triaged work unit.
• Execution leakage: branch creation, file edits, PR creation, and review compliance belong to the receiving execution session, not /triage.
• Silent split or merge: changing work-unit cardinality without surfacing the grouping rationale hides the decision the user must recognize.
• Work unit as issue dump: an externalized WorkUnitRecord must carry the fused problem frame, scope, exclusions, and verification expectations Phase 3 through 5 produced; it is not a pasted issue list.
• Re-authored handoff: restating the record's contents into a bespoke initial-prompt brief at Phase 7 instead of pointing at the record. The restatement is a second representation with no enforcement channel binding it to the record, and it drifts silently as the record moves.

Operational checklist (per cycle)

• Phase 0 issue scope is explicit, session-supplied, pasted, or defaulted to current open backlog through metadata intake
• Phase 0 TriageLoad records IssueLoad, RepoLoad, MappingLoad, and IntentAmbiguity
• Phase 0 intake posture is classified as small, medium, or large from TriageLoad before full substrate reads
• Large intake has an IntakeIntent crystallized through /elicit before filtered full-substrate reads
• Phase 1 RawIssueSet includes issue numbers and relevant comments / links / blockers
• Phase 2 grouping map surfaced before work-unit formation
• Phase 3 NormalizedProblemFrame records evidence, conflicts, missing context, and exclusions
• Phase 4 NorthstarFusion records preserved / transformed / dropped claims
• Phase 5 FocusedWorkUnit readiness and split rationale are explicit
• Phase 6 route choice is selected by the user before any handoff is prepared
• Phase 7 externalizes each routed work unit to a WorkUnitRecord (anchor-issue comment or issue-body triage section) carrying the FocusedWorkUnit/NormalizedProblemFrame/NorthstarFusion/issue-provenance substrate, then hands the receiving session a navigation block over that record in the shape Phase 7 declares, with a collaborator Role declared; re-triage skips this step