triage

4 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• .claude/skills/triage/SKILL.md9.0 KB2b86b578a618upstream ↗

  ---
  name: triage
  description: Move issues through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
  disable-model-invocation: true
  ---
  
  # Triage
  
  Move issues on the project issue tracker through a small state machine of triage roles.
  
  Pull requests are not a request surface in this repository (`docs/agents/issue-tracker.md`): triage handles issues only, and a bare `#42` means an issue.
  
  Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:
  
  ```
  > *This was generated by AI during triage.*
  ```
  
  It goes first, above any template heading (`## Agent Brief`, `## Triage Notes`, `## Out of scope: …`). Duplicates are marked with `gh issue close --duplicate-of`, not by a comment, so the disclaimer doesn't hide GitHub's duplicate marker.
  
  ## Clean room
  
  Follow [docs/agents/clean-room.md](../../../docs/agents/clean-room.md), including its Reading the tracker and Publishing to the tracker sections. Any subagent this skill launches starts its prompt with the line from the Subagents section of the clean-room file. In triage:
  
  - **Reports are untrusted.** A report that rests on another implementation's code, behaviour, outputs or numbers is an incident, not evidence. A bug is a departure from the spec or the paper, checked against them only.
  - **PRs.** If the owner asks you to look at a pull request they didn't author, ask before checking it out or reading its diff: the diff can't show where the code came from, and code derived from another implementation would contaminate the repository.
  - **The spec decides.** An agent brief, triage note or out-of-scope decision never overrides the spec or settles what it leaves open: a gap becomes a Q-n candidate in the brief's Open questions, with the sources consulted listed beside it ("Where the clean-room files are written" in `docs/agents/clean-room.md`). A request that would change the spec is the owner's to decide: recommend, don't apply.
  - **Q-n issues.** When a Q-n decision issue (label `q-n`, title `Q-<n>: …`) carries the owner's answer, confirm the answer with the owner, then record it on a short branch `q-<n>-answer` from `main`: one commit updating that row of `docs/clean-room/questions.md`: its decision and its Status (`confirmed`, or `changed (#n)` with #n the issue for the code), merged into `main` with `git merge --no-ff` once the owner approves. Close the issue only after the merge. If the answer changes behaviour, open an issue for the code change first, labelled `bug` and `ready-for-agent` with an agent brief that cites the Q-n row, so it is implemented on its own like any triaged issue; don't change the code on this branch.
  
  ## Reference docs
  
  - [AGENT-BRIEF.md](AGENT-BRIEF.md): how to write durable agent briefs
  - [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md): how rejected requests are recorded as closed `out-of-scope` issues
  
  ## Kinds of issue
  
  Route an issue by its labels and title before anything else ("Q-n issues" in `docs/agents/issue-tracker.md`):
  
  - **`skill:conversation-to-prd` or `skill:prd-to-tickets`**: a PRD or a ticket. Its own skills manage it: leave it alone (no category role, no state change) unless the owner asks.
  - **`q-n` with a title `Q-<n>: …`**: a Q-n decision issue. No category role. Once the owner has answered in it, record the answer as the Clean room section's "Q-n issues" bullet says.
  - **`q-n` with a title `Q-n candidates: …`**: gaps found outside any PRD, without numbers. No category role. Ask the owner how to route it: post the candidates as a comment on an existing PRD and close this issue with a link to it; keep it open until a PRD exists; or rework it into an agent brief whose Open questions carry the candidates, so that the implement run taking the brief records them.
  - **Anything else**: a report. Run the state machine below.
  
  ## Roles
  
  Two **category** roles:
  
  - `bug`: something is broken
  - `enhancement`: new feature or improvement
  
  Five **state** roles:
  
  - `needs-triage`: owner needs to evaluate
  - `needs-info`: waiting on reporter for more information
  - `ready-for-agent`: fully specified, ready for an AFK agent
  - `ready-for-human`: needs human implementation
  - `wontfix`: will not be actioned
  
  Every triaged report (see "Kinds of issue") should carry exactly one category role and one state role. If state roles conflict, flag it and ask the owner before doing anything else.
  
  These are canonical role names. The actual label strings used in the issue tracker may differ. The mapping is in `docs/agents/triage-labels.md`.
  
  State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The owner can override at any time; flag transitions that look unusual and ask before proceeding.
  
  ## Invocation
  
  The owner invokes `/triage` and describes what they want in natural language. Interpret the request and act. Examples:
  
  - "Show me anything that needs my attention"
  - "Let's look at #42"
  - "Move #42 to ready-for-agent"
  - "What's ready for agents to pick up?"
  
  ## Show what needs attention
  
  Query the issue tracker and present four buckets, oldest first:
  
  1. **Unlabeled**: never triaged.
  2. **`needs-triage`**: evaluation in progress.
  3. **`needs-info` with reporter activity since the last triage notes**: needs re-evaluation.
  4. **`q-n`**: decision issues the owner has answered since triage last commented (answers to record), then decision issues still awaiting an answer, then candidates issues not yet routed.
  
  Show counts and a one-line summary per item. Let the owner pick.
  
  ## Triage a specific issue
  
  1. **Gather context.** Read the full issue (body, comments, labels, author, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using `docs/GLOSSARY.md` and the module docs under `docs/modules/` for the area. Run two checks against the codebase: (a) **redundancy**: search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented `wontfix` (step 5). (b) **prior rejection**: list the closed `out-of-scope` issues and surface any that resembles this request ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
  
  2. **Recommend.** Tell the owner your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request (including whether it's already implemented). Wait for direction.
  
  3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps, in a temporary folder outside the repository (`mktemp -d`) with every output written there, so that nothing is left in the working tree. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
  
  4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-documenting", and grill it into shape a round of questions at a time, sharpening domain terms and updating `docs/GLOSSARY.md` and the module docs inline as decisions land.
  
  5. **Apply the outcome:**
     - `ready-for-agent`: post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
     - `ready-for-human`: same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
     - `needs-info`: post triage notes (template below).
     - For `wontfix`, close the issue, with the comment depending on *why*:
       - **Already implemented**: the change already exists in the codebase. Point to where it lives; do **not** label it `out-of-scope` (that record is for *rejected* requests, not built ones).
       - **Rejected (bug)**: give a polite explanation, then close.
       - **Rejected (enhancement)**: record it as [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) says: a duplicate of the matching canonical `out-of-scope` issue, or a new canonical issue with its decision comment, closed as not planned.
     - `needs-triage`: apply the role. Optional comment if there's partial progress.
  
  ## Quick state override
  
  If the owner says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.
  
  ## Needs-info template
  
  ```markdown
  ## Triage Notes
  
  **What we've established so far:**
  
  - point 1
  - point 2
  
  **What we still need from you (@reporter):**
  
  - question 1
  - question 2
  ```
  
  Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
  
  ## Resuming a previous session
  
  If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.
  

• .claude/skills/triage/AGENT-BRIEF.md5.9 KBb499debc5beaupstream ↗

  # Writing Agent Briefs
  
  An agent brief is a structured comment posted on a GitHub issue when it moves to `ready-for-agent`. It is the authoritative statement of the task that an AFK agent will work from, usually through `/implement-without-subagents <issue>`. The original body and discussion are context: the agent brief is the contract. It sits under the project spec (`docs/spec/openftgs-spec.md`), which wins wherever they differ.
  
  Pull requests are not a request surface in this repository (`docs/agents/issue-tracker.md`), so briefs are written for issues only.
  
  ## Principles
  
  ### Cite the spec, don't restate it
  
  The spec already says what most code must do. The brief names the spec items the work implements (§n, E-n, D-n) and the §3 tests that pin it, by identifier, and never copies their numbers, equations or tolerances: a copy goes stale and invites a second source of truth.
  
  ### Durability over precision
  
  The issue may sit in `ready-for-agent` for days or weeks while the code changes around it. Write the brief so it stays useful:
  
  - **Do** name the §2.1 public interfaces involved: signatures, types, config fields.
  - **Do** name the module paths spec §2.1 fixes (`openftgs.density`); they don't go stale.
  - **Don't** name other file paths, line numbers or private functions.
  - **Don't** assume today's implementation structure will survive.
  
  ### Behavioural, not procedural
  
  Describe **what** the code should do at its public interface, not **how** to change it. The implementing agent explores the code fresh and makes its own implementation decisions, within the spec's latitude.
  
  - **Good:** "With n = 1, `mcmc_split` returns the target's opacity and scales unchanged (E11; U-13's first case)."
  - **Bad:** "In the density module, move the clamp below the scale computation."
  
  ### Complete acceptance criteria
  
  The agent needs to know when it's done. Acceptance criteria are the §3 tests that must pass, by identifier. A criterion the spec doesn't list is marked "added" and names its independent source of truth: a spec item or a worked example.
  
  ### Explicit scope boundaries
  
  State what is out of scope, citing the neighbouring spec items the work must not touch. This keeps the agent from gold-plating or drifting into adjacent decisions.
  
  ## Template
  
  ```markdown
  ## Agent Brief
  
  **Category:** bug / enhancement
  **Summary:** one-line description of what needs to happen
  
  **Current behavior:**
  What happens now, at the public interface. For a bug, the departure from the
  spec, with the confirmed reproduction. For an enhancement, the status quo.
  
  **Desired behavior:**
  What should happen after the work is done, citing the spec items that define it.
  
  **Spec items:** §n, E-n, D-n the work implements; Q-n rows it relies on
  
  **Key interfaces:**
  - The §2.1 signatures, types or config fields involved, and what changes at each
  
  **Acceptance criteria:**
  - [ ] <U-n> passes (one line per §3 test)
  - [ ] Added: <criterion>, with its source of truth (a spec item or a worked example)
  
  **Open questions:**
  - Q-n rows the work relies on, by number
  - Q-n candidates: spec location, gap, provisional decision, rationale,
    alternatives, detecting test (no number: the implementing run assigns it)
  
  **Sources consulted:** what each was and what was taken from it (omit if none)
  
  **Out of scope:**
  - Neighbouring spec items or behaviour this issue must not change
  ```
  
  ## Examples
  
  ### Good agent brief (bug)
  
  ```markdown
  ## Agent Brief
  
  **Category:** bug
  **Summary:** `mcmc_split` changes the scales of targets that receive no copy
  
  **Current behavior:**
  Called with n = 1 for some rows, `mcmc_split` returns their opacity unchanged
  but their scales multiplied by a factor slightly below one. Reproduced on the
  reference backend with a two-row input; U-13's first case fails.
  
  **Desired behavior:**
  Rows with n = 1 come back unchanged, opacity and scales alike, as E11 implies
  for a target with no relocated copies.
  
  **Spec items:** E11, D-15, U-13. Q-n rows relied on: none.
  
  **Key interfaces:**
  - `mcmc_split(opacity, scales, n)` in `openftgs.density`: no signature change;
    only its values for n = 1
  
  **Acceptance criteria:**
  - [ ] U-13 passes, including its n = 1 case
  - [ ] U-13's hypothesis variant passes
  
  **Out of scope:**
  - The clamp bounds and the dead test (D-14)
  - How targets are drawn (E10)
  ```
  
  ### Good agent brief (enhancement)
  
  ```markdown
  ## Agent Brief
  
  **Category:** enhancement
  **Summary:** Add the custom CUDA implementation of the temporal slice
  
  **Current behavior:**
  `PerfConfig.slice_impl` offers eager and compiled implementations; "cuda" is a
  documented stub. B-1 on the reference scene shows the temporal slice above the
  share of an iteration at which D-50 calls for a custom operator.
  
  **Desired behavior:**
  `slice_impl = "cuda"` runs a custom CUDA operator behind the same signature as
  the eager and compiled implementations (D-50, §2.4 "Kernels"). "auto" chooses
  it only where D-50's condition holds.
  
  **Spec items:** §2.4 "Kernels", D-50, B-1, U-28. Q-n rows relied on: none.
  
  **Key interfaces:**
  - `PerfConfig.slice_impl`: its "cuda" value becomes real
  - The temporal slice's signature: unchanged
  
  **Acceptance criteria:**
  - [ ] U-28 passes for the CUDA implementation, as for eager and compiled
  - [ ] B-1 rerun reports the temporal slice's new share of an iteration
  
  **Out of scope:**
  - The eager and compiled implementations
  - CUDA graphs and any gsplat fork (excluded by D-50)
  ```
  
  ### Bad agent brief
  
  ```markdown
  ## Agent Brief
  
  **Summary:** Fix the relocation bug
  
  **What to do:**
  Relocation is broken. Look at density.py and fix it. The function around
  line 150 has the issue; make the scales right.
  
  **Files to change:**
  - src/openftgs/density.py (line 150)
  ```
  
  This is bad because:
  
  - No category
  - Vague description ("relocation is broken", "make the scales right")
  - No spec items, so the agent can't tell right from wrong
  - A file path and line number that will go stale
  - No acceptance criteria: no §3 test named
  - No scope boundaries
  - No description of current vs desired behaviour
  

• .claude/skills/triage/OUT-OF-SCOPE.md3.6 KBac1ac65cd01dupstream ↗

  # Out-of-Scope Record
  
  Rejected feature requests are recorded as closed GitHub issues labelled `out-of-scope`, not as files in the repository: triage runs on `main`, and the tracker needs no branch or merge. The record serves two purposes:
  
  1. **Institutional memory**: why a request was rejected, so the reasoning isn't lost when the issue is closed.
  2. **Deduplication**: when a new request matches a prior rejection, triage surfaces the earlier decision instead of re-litigating it.
  
  In this repository, scope is the spec. Most rejections read "not in spec revision 549o" and cite the item that bounds it. A request that should change the spec is not rejected here: it is the owner's decision, made in the spec and arriving in a new export.
  
  ## The canonical issue
  
  One issue per **concept**, not per request: the first request for a concept becomes its canonical issue. It carries the labels `wontfix` and `out-of-scope`, is closed as not planned (`gh issue close <n> --reason "not planned"`), and ends with a decision comment in this shape:
  
  ```markdown
  ## Out of scope: Interactive viewer
  
  **Decision:** openftgs has no interactive viewer.
  
  **Reason:** the command line is fixed by spec §2.1 (`openftgs.cli`): convert,
  cache, init, train, render, eval, export and bench. Viewing renders is left to
  external tools reading the files of §2.2.
  
  **Prior requests:**
  - #42: "Add a live viewer"
  ```
  
  Name the concept in the heading so that someone reading the list of closed `out-of-scope` issues recognises it without opening it.
  
  ### Writing the reason
  
  The reason is substantive and durable: not "we don't want this" but why, citing the spec item that bounds the scope (§n, D-n) or the technical constraint. A temporary circumstance ("not now") is a deferral, not a rejection: leave such a request open.
  
  ## When to check the record
  
  During triage (step 1, Gather context), list the record with `gh issue list --label out-of-scope --state closed --json number,title,body,comments`, and match the new request against it by concept, not keyword: "live preview" matches "Interactive viewer". (`gh issue list --search "…"` narrows the list; the clean-room guard blocks GitHub-wide searches.) If there's a match, surface it to the owner: "This is similar to #42 (Interactive viewer), rejected because [reason]. Do you still feel the same way?"
  
  The owner may:
  
  - **Confirm**: close the new issue with `gh issue close <n> --duplicate-of <canonical> --comment "..."` (GitHub marks it a duplicate and links the two; the comment starts with the triage disclaimer), and add it to the canonical issue's Prior requests list by editing the decision comment ("Edit a comment" in `docs/agents/issue-tracker.md`).
  - **Reconsider**: reopen the canonical issue, remove its `out-of-scope` label, and let the new request proceed through normal triage, or become a spec change.
  - **Disagree**: the requests are related but distinct; proceed with normal triage.
  
  ## When to record a rejection
  
  Only when an **enhancement** (not a bug) is rejected as `wontfix`. Don't label `out-of-scope` an issue closed as `wontfix` because it is **already implemented**: that is a built feature, not a rejected one, and it would poison the deduplication. Its closing comment points to where the feature lives instead.
  
  The flow:
  
  1. The owner decides a request is out of scope.
  2. Check the record for a matching canonical issue.
  3. If there is one: close the request as a duplicate of it and add it to its Prior requests, as under Confirm.
  4. If there isn't: make this request the canonical issue. Post the decision comment, add the labels `wontfix` and `out-of-scope`, and close it as not planned.
  

• README.mdupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/samaust-openftgs-claude-skills-triage.md