reticlehq/reticle

debug-broken-ui

Find out why something in a running web app does not work, when the console is empty and the code looks correct.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/reticlehq/reticle --skill debug-broken-ui

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

The app is broken and the code looks fine

Reading the source again will not tell you why. The evidence is in the running app, and most of it never reaches the screen: the request that failed, the store that never moved, the handler that was never bound, the element covered by something invisible.

Reticle reads all of it from inside the page. Not installed? RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init, then the `install-and-verify` skill.

Do not start by guessing. Start by reproducing.

reticle_look({ action: "page", sessionId, mode: "interactive" })   // controls only, with refs
reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "element", query: { testid: "..." } } })

The verdict already narrows it: no / contradicted means a channel saw something incompatible with the UI: you have the bug. unknown means Reticle drove it and could not tell, which is a different investigation from "it failed".

Read the act result before you call anything else. Its summary block already carries the whole causal window of that one click: net {total, errors, headline}, consoleErrors, stateDiffs [{path, from, to}], storageDiffs [{key, from, to}], route, signals, layoutShift, longTasks: real before→after diffs, not counts. The console, network, storage and state calls below are for going DEEPER into something the summary already pointed at. Calling all three straight after an act pays three model round trips (and, in an approval-gated client, three human clicks) for evidence you were already holding.

summary.stateUnwatched: true means the state channel is dark: no subscribable store is registered, so an empty stateDiffs means unwatched, not unchanged, and no state-based conclusion is available until someone registers the store. It is the one field here that is about your instrumentation rather than about the app.

When the summary does point somewhere, read that channel scoped to what you just did: pass since from the act result, or you are reading a buffer that predates the click:

reticle_observe({ action: "console", sessionId, since })
reticle_observe({ action: "network", sessionId, since })
reticle_look({ action: "state", sessionId, store })

The diagnosis table

What you seeWhat it isNext
No request fired at allthe handler is not bound, or a client cache served a stale valuereticle_look { action: "element" } the element for its file:line; check the cache if it is TanStack Query
Request fired, 4xx/5xxa real backend failure the UI swallowedthe response body is in the network entry
2xx but nothing changedthe app never read the response: verdict says outcome_unreadusually a real bug in the success path
Request fine, DOM fine, store staleUI-vs-state desync, invisible to any screenshotreticle_look { action: "state" } is the only witness; this is the highest-value read here
Click did nothing, no errorthe control is dead, occluded, or disabledreticle_look { action: "element" } returns occluded, box (0×0), styles.cursor, opacity
Element "not found" that you can seevirtualised list has not mounted itreticle_scroll_to. A query that misses is not evidence of absence
Looks logged in, behaves logged outthe token never persistedreticle_storage
Console error that predates your clicka pre-existing fault, not your bugcall it out before continuing

Get the file, not a theory

reticle_look({ action: "element", sessionId, ref })

Returns the component and source: { file, line } for the element you are looking at, plus whether it is occluded, sized, disabled or off-theme. That is the pointer to open. End the investigation with a location, not a hypothesis.

When the flow is long

Do not ping-pong act → snapshot → act → snapshot to find the failing step. Drive the journey with reticle_act { steps: [...] } and assert once; the first step whose consequence fails is the one to look at, and you paid a fraction of the calls to find it.

Before you say it is fixed

Re-run the reproduction as a verdict (reticle_act_and_wait with the consequence named up front) rather than eyeballing the page. A fix confirmed by looking at it is the failure mode that created this ticket.

And never weaken the check to make it pass.


Troubleshooting Reticle itself (as opposed to the app): curl https://docs.reticle.sh/troubleshooting.md. Everything else: curl https://docs.reticle.sh/llms.txt. If Reticle could not see something you needed, reticle_session { action: "feedback" } with kind: "gap".

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
reticlehq
커뮤니티

reticle

Install, instrument and verify this running web app from the inside (DOM, network, routing, console and framework state) instead of screenshots or guessing. Drives one real flow end to end and returns a verdict with the file:line to fix. Use when the user asks to set up or install Reticle, when a user-facing change needs proving before you call it done, when a test passes but the UI is broken, or when the user types /reticle.

1시간 설치 수
1
GitHub Stars
1.3천
업데이트
10월 30일
reticlehq
커뮤니티

audit-my-app

Sweep a whole running web app for what is broken, without writing a script or knowing the codebase. Clicks every reachable control and reports dead buttons, console errors, failed requests, and places where the API and the screen disagree. Use on an unfamiliar codebase, before a release, after a big merge or dependency bump, when the user asks for a smoke test or a health check, or when someone says "just check everything still works".

1시간 설치 수
1
GitHub Stars
900
업데이트
9월 26일
reticlehq
커뮤니티

fix-what-i-pointed-at

Pick up the bugs a human flagged by pointing at them in the running app, each arriving with the element, the note they typed, and the source file and line. Use when the user says they marked or flagged something, when starting a session on an app someone has been clicking through, when a designer or PM has left feedback in the UI, or when the user describes a problem as "that button there" without saying which file.

1시간 설치 수
1
GitHub Stars
900
업데이트
9월 26일
reticlehq
커뮤니티

replay-user-flows

Turn a user journey you just clicked through into a saved regression check that re-runs deterministically, with no model in the loop and no test code to write. Use when you have driven the same flow twice, when the user wants regression coverage without a Playwright suite, when a refactor needs proving against every existing journey, or when re-verifying by hand is costing a full drive every time.

1시간 설치 수
1
GitHub Stars
900
업데이트
9월 26일