Triage Frontend Ticket

Triage frontend ticket

Input: one Linear ticket URL or identifier (e.g. <ISSUE-ID>). If none was given, ask with AskUserQuestion and stop until given.

Repo: the lago-front checkout (front/ in the lago monorepo). If the session is not in lago-front, STOP — this skill reasons about this codebase only.

Output: one comment posted on the ticket, and — only for a ticket sitting in Triage that the analysis actually resolved — a move to Backlog. Nothing else on Linear is touched.

Who reads that comment: whoever picks the ticket up next — a human deciding whether to schedule it, a developer opening the editor, or an agent implementing it. Assume none of them will redo the analysis. So the comment is a handoff document: everything needed to start work is in it, in a form that reads as well to a person as it parses to an agent. That is what step 6's Implementation handoff block is for.

This skill is deliberately pipeline-agnostic. It ends at the posted comment and makes no assumption about how the work gets done afterwards — by hand, by an agent, or by an automated pipeline. If your team uses one that reads ticket comments (/loop-run does, through loop-spec), the handoff block is already in the shape it needs; if not, it is simply a well-specified ticket.

Read LEARNINGS.md (alongside this file) before you judge anything. It holds rules learned from real outcomes and overrides the defaults here where they conflict — within the limits stated in that file: a learning may tune judgement, never soften a guardrail.

Create a todo per numbered step below before starting.

1. Fetch, gate, classify

Extract the issue id ([A-Z]+-\d+), then reset the review budget so a re-triage starts clean:

front/scripts/iter-budget.sh <ISSUE-ID> reset triage-review
front/scripts/analysis-depth.sh <ISSUE-ID> reset

Fetch via Linear MCP get_issue (with includeRelations) and list_comments — repro steps, scope changes and decisions often live only in comments, and a Slack attachment subtitle often holds the original report.

Then enumerate the attachments and say what you could and could not read. A Loom or a screenshot is frequently the only place the actual gesture exists. You cannot watch a video: state that, ask the operator to describe what happens in it, and never replace it with a plausible reconstruction — a repro you invented is how an analysis ends up explaining a defect nobody reported.

Check every gate in order. Exactly one of them posts anything; the rest stop silently. Do not improvise a third outcome.

• Not analyzable → post the Needs info comment (step 6) with the footer (step 8), then stop: no independent review (there is no finding to re-derive) and no status move (the ticket is still waiting on the reporter).
• Every other failure → STOP, report to the operator, post nothing.

Then classify the ticket, because it decides what the analysis has to prove:

Mixed ticket ("it's wrong, and while we're there make it configurable") → treat the defect as primary, and cover the request under Scope beyond the defect. When the label and the wording disagree, the wording wins; say which you picked.

Is there anything to analyse at all?

Some tickets already name what to change and where — "change this wording to that". An analysis would only restate them. Record that and stop:

front/scripts/analysis-depth.sh <ISSUE-ID> set skip

Post a one-line comment saying it is already actionable, or nothing at all, and finish.

Everything else gets the analysis. How deep it goes is not decided here — you cannot know what a change touches before reading the code. That call comes at step 5, once you do.

2. Ground it in the project's own rules, then read the code

The repo documents itself, and skipping that is how an analysis ends up correct about the symptom and wrong about the fix.

2a. Check the symptom against known regression classes

CLAUDE.md and the lago-frontend-patterns skill it points to are not only style - they record defect classes together with the symptom they produce. The table below turns a reported symptom into the first place to look. Nothing in it is a conclusion: a row that matches is a hypothesis, and the analysis stands or falls on confirming it at the actual call site.

How to use a match: open the call site and check whether the documented cause is actually present there. Confirmed → cite the rule and take the prescribed fix rather than inventing one. Not present → the row was a wrong guess; drop it and keep reading the code. The symptom in a report is a description of what someone saw, and several causes produce the same description.

A row that matches never enters the comment as the cause on its own. It has to survive step 3 like any other claim: the evidence is what makes it a finding, and "the symptom matches a documented pattern" is not evidence.

No match means nothing at all — most defects are not in this table.

2b. Read what binds this area

• CLAUDE.md at the root — always. It is prescriptive, not advisory.
• The subsystem skill CLAUDE.md points to, whenever the area is one of its topics: lago-frontend-patterns. It carries the full rules those sections used to hold inline.
• The on-demand docs in .agents/docs/ for the area involved: folder-architecture, graphql-fragments, testing-practices, documentation. (typescript-conventions is already loaded in every session.)
• The nearest-neighbour code. The closest existing feature doing the same thing is the pattern of record. Read it before proposing a shape.

Two things this changes about the fix, not just the analysis:

• The fix must be the sanctioned pattern, not merely a working one. A new drawer is the use<Feature>Drawer hook, never a forwardRef + DrawerRef; a dialog is one of the three hooks; a new translation key comes from pnpm translations:add, never hand-written.
• A legacy pattern next door is not permission to copy it. The lago-frontend-patterns skill (references/drawers.md) says this outright, and it holds generally: three generations coexist and only one is allowed in new code. Cite the reference site the docs name, so whoever implements it copies from the right place.

For a change request, conventions are part of the answer, not a footnote: a request that fights a documented convention is a caveat at minimum, and sometimes the reason the honest verdict is feasible with caveats rather than feasible as asked.

2c. Then follow the chain

Generated files are read with a scalpel. src/generated/graphql.tsx holds single lines tens of thousands of characters long — one permissions blob repeated per operation. A bare grep for a common word there returns those whole lines and burns a large share of the run's budget for nothing. Match the shape you want and print only that:

# the argument list of one query, not every line mentioning it
grep -n "QueryMembershipsArgs" -A 6 src/generated/graphql.tsx

# a field's declared type, without the surrounding blob
grep -o "issuingDate[A-Za-z]*?*: [A-Za-z'\[\]]*" src/generated/graphql.tsx | sort -u

The same applies to lockfiles, snapshots and translation bundles.

Read the actual code. Grep for the feature, the filter key, the component, the translation key — whatever the ticket names — and follow the chain end to end. Name real symbols and file.ts:line paths.

For a defect, the two ends are usually in different files and the bug is the disagreement between them:

• where the value is produced or stored (form handler, URL param writer, serializer, GraphQL variable builder)
• where it is displayed (formatter, label builder, cell renderer)

A default argument on the display side (fallback timezone, locale, currency, empty state) is the single most common root cause: producer and consumer each look correct in isolation.

For a change request, map instead:

• the current behavior, precisely — this is the baseline the request is measured against, and reporters are often wrong about it
• every call site that would have to change, not just the one the ticket names
• what constrains the change: GraphQL schema (does the API already return this field?), design-system components available, CLAUDE.md conventions that dictate the shape, translations, migrations
• whether it is already possible by another route — some requests are answered by pointing at an existing feature

An analysis that describes behavior without citing code is not done.

3. Ground it in something re-runnable

A conclusion with no evidence beyond prose is not a conclusion. Produce at least one artifact a reader can re-run or point at:

• a node -e one-liner through the real library (luxon, intl, currency helpers) showing input → actual vs expected
• an existing test whose expectations reveal the assumption (quote path + line)
• a scoped pnpm test <path> run — never the full suite
• for a change request: the GraphQL schema field (or its absence) in src/generated/graphql.tsx, the existing component that already does the thing, the full grep of call sites to be touched
• for visual/layout claims, the concrete DOM/class/style that produces it

Build the input from what the code actually stores, not from the ticket's screenshot. Reconstruct that value from step 2 first.

3a. For interaction, layout and rendering symptoms, a harness is not a reproduction

A jest harness or a node -e snippet proves a mechanism exists. It cannot prove that mechanism is what the reporter hit — jsdom has no layout, no scroll and no paint, which is exactly where this class of defect lives. When the symptom is "the menu doesn't open", "nothing happens when I click", "it's in the wrong place", the evidence has to come from the running app on the reported surface (the /qa-session skill resolves the worktree and port). Until then every code-derived cause is a hypothesis, however well it reads.

3b. Precondition check — does the reporter's repro actually trigger your cause?

The single check that catches a plausible-but-wrong analysis. For each cause you propose, write down:

A cause whose precondition is narrower than the report explains less than it looks like it does — say so instead of letting the reader assume it covers the ticket. If no cause is triggered by the reported steps, the real cause is still unfound: the verdict is cannot determine on the reported symptom, plus whatever adjacent defects you did confirm, listed as adjacent. Never present them as the answer.

Worked failure this rule exists to prevent: a report said "paste markdown, the block menu never opens". The analysis found two genuine defects — a stale captured position in a widget, and an unwrapped <hr> — and both were real. But the first needs an edit that leaves doc.childCount unchanged and the second only ever affected dividers, while a plain multi-block paste rebuilds every decoration and works fine on unfixed code. The reported symptom was a third defect, in a file the analysis had explicitly fenced off as correct.

4. Verdict

A ticket reporting several symptoms gets a verdict per symptom. They routinely have different causes and different answers — one fixable today, another blocked on an API change. Collapsing them blocks work that could ship, or promises work that cannot. Decompose the report into its separate claims and judge each on its own; a combined "partly X, partly Y" headline is fine, the body has to keep them apart.

Defect — pick one:

• confirmed — real, with the mechanism
• not a bug — plus the reason the reporter saw what they saw (a stale cache, a different org setting, correct-but-confusing UX)
• cannot determine — plus what is missing

Change request — pick one:

• feasible as asked — the change is contained; say what it touches
• feasible with caveats — name each caveat: a schema change needed API-side, a convention that forces a different shape, a migration, a design decision left open
• blocked — name the specific blocker and who unblocks it (API field missing, product decision, dependency)

5. Blast radius / scope

Whatever mechanism is involved, grep for every other call site sharing it. Split into affected and unaffected, and say why each unaffected one is safe.

When the mechanism is a shared key or identifier — a URL param, a localStorage key, a constant, a cache key, an enum value — enumerate both directions: every consumer that reads it, and every producer that writes it, deep links built in unrelated pages included. Grep the exported constant, then the bare literal too in case somewhere hardcodes it.

Changing the shape of a shared value while missing one producer is a silent break: the writer keeps emitting the old shape, the reader matches nothing, and no test fails because the two live in different files. A fix list that changes a key's format without naming every writer is incomplete.

A file may be declared out of scope only after the symptom has been reproduced, and only for code proven unrelated to that reproduction. "This guard is correct" is a claim about one line, not a licence to stop reading the file — the defect is regularly a few lines below the part you verified, and a non-goal written early becomes a blindfold the implementer inherits.

This is where triage earns its keep — the reporter sees one surface, the code usually has more. Report affected siblings even when out of the ticket's scope. For a change request the same sweep answers "where else does this have to change to stay consistent", which is usually the real cost of the ticket.

Now price the review

You know what the change touches, so this is the moment to decide whether it needs an independent review. That review is the expensive part of this skill: spend it where being wrong would go unnoticed, not on everything.

front/scripts/analysis-depth.sh <ISSUE-ID> set <shallow|full>

full — the review runs. Any one of:

• the fix reaches more than one area of the code
• a shared key or identifier, or a derived value
• pagination, cache, timezone or currency semantics
• the failure mode is silent — a wrong number, a filter matching nothing, a link that quietly stops working

shallow — the review is skipped. The change is contained to one area, nobody else reads or writes the value, and being wrong is obvious to whoever opens the page. CLAUDE.md and the conventions are check enough at this size.

Do not count files. A source file and its test are one unit of work, not two — counting them would put everything in full and make shallow unreachable, which is not the intent. Count areas: a component plus its own test is one; a component, a hook and a cache policy is three.

The test is the failure mode, not the size of the diff. One line changing how an amount is formatted is full — trivial diff, invisible when wrong, and the review is what catches it. A twenty-line layout rewrite can be shallow — wrong is obvious at a glance.

Uncertain between the two → full.

Escalation is one-way and enforced. analysis-depth.sh refuses to move back down: shallow is the tier that skips the review, and the moment to be tempted into skipping it is exactly when the work turns out bigger than hoped. If anything surfaces while drafting — a second area to touch, a value read somewhere else, a way to be wrong unnoticed — escalate and take the review.