triage

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

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:

Use the load axes to choose an intake posture:

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.
12. Preserve issue provenance (Architectural — provenance continuity): Every problem frame, work unit, and composed handoff cites the source issue numbers that contributed to it.
13. Blocked work stays visible (Derived — Surfacing over Deciding): If an issue group is blocked, stale, or needs-info, emit that as a work-unit disposition or re-triage note rather than dropping it.
14. Pointer, not a second copy (Architectural — externalization boundary): /triage forms and routes focused work units and externalizes each routed unit to a WorkUnitRecord; the handoff is a navigation block over that record, not a re-authored restatement of its contents. A second copy is not coupled by any enforcement channel to the record it describes, so it can silently disagree with it — the pointer removes that failure class rather than auditing for it.

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