showdar-skills 0.2.0

package/skills/showdar-debug/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: showdar-debug
+description: Use when observed behavior fails through crashes, regressions, build failures, races, networking, memory, or performance issues.
+---
+
+# Showdar Debug
+
+## Purpose
+
+- Find and confirm root cause before modifying production behavior.
+- Turn logs, stack traces, timing, state, profiler data, and reproduction steps into falsifiable hypotheses.
+- Avoid symptom patches that hide defects or create new regressions.
+- End with a minimal fix and regression proof when implementation is requested.
+- Read `references/hypothesis-driven-debugging.md` for experiment discipline.
+- Use `data/failure-patterns.csv` as a hypothesis prompt, never as automatic diagnosis.
+
+## When to use
+
+- Crash, exception, wrong state, intermittent failure, regression, hang, build failure, or unexpected output.
+- Performance problem such as jank, latency, memory growth, startup cost, or event-loop/thread blocking.
+- Networking/auth/cache bugs where timing or retry behavior is unclear.
+- A previous fix did not resolve the symptom and root cause needs re-evaluation.
+
+## When not to use
+
+- Root cause and fix are already proven and only implementation remains.
+- The user asks only for architecture understanding or code review.
+- A live production incident requires external observability tools unavailable here; use this skill to structure evidence but do not invent telemetry.
+- Do not run destructive cleanup commands merely to “see if it helps”.
+
+## Inputs and assumptions
+
+- Exact symptom, expected behavior, environment/platform, and any available error/log/stack trace.
+- Reproduction steps or a path to create a deterministic reproducer.
+- Repository/build context; `scripts/collect-context.mjs` may collect read-only stack/git/runtime signals.
+- Sensitive logs must be redacted before output.
+- A hypothesis is not a conclusion until an experiment distinguishes it from alternatives.
+
+## Non-negotiable rules
+
+- Do not edit production code before collecting enough evidence to state at least one falsifiable hypothesis.
+- Start from the first causal error/event, not the final cascade message.
+- Change one variable per diagnostic experiment when practical.
+- Preserve logs/profiler/test evidence that confirms or falsifies each hypothesis.
+- Reject contradicted hypotheses instead of adding patches around them.
+- Cache deletion, dependency reinstall, clean build, and reboot are experiments only when they test a cache/environment hypothesis.
+- Never log or expose credentials/tokens/full sensitive payloads.
+- For performance, measure a named path before claiming improvement.
+
+## Workflow
+
+### Phase 1 — reproduce and bound
+- Write the shortest reliable reproduction, environment, expected result, and actual result.
+- Determine whether failure is deterministic, timing-dependent, data-dependent, platform-specific, or release-only.
+- Reduce unrelated variables without changing the failing invariant.
+
+### Phase 2 — gather evidence
+- Capture stack/error, relevant logs, request/state timeline, failing build task, profiler/thread/memory evidence as appropriate.
+- Inspect recent relevant diff/version/environment changes.
+- Collect context with `scripts/collect-context.mjs` when useful.
+
+### Phase 3 — classify
+- Classify into state/lifecycle, async/race, network/auth/cache, build/toolchain, memory/resource, performance/thread, persistence/data, or contract/serialization.
+- Read the relevant reference file before designing experiments.
+
+### Phase 4 — hypotheses
+- List 2–4 ranked hypotheses with supporting and contradicting evidence.
+- For each, define a cheap experiment and predicted result.
+- Prefer experiments that distinguish multiple hypotheses at once.
+
+### Phase 5 — experiment
+- Run one controlled experiment.
+- Record result and update hypothesis ranking.
+- Repeat until one root cause is confirmed or evidence forces escalation.
+
+### Phase 6 — regression proof
+- Create the lowest-level automated test/scenario that fails for the confirmed defect.
+- Confirm failure is due to the root cause, not fixture/test error.
+
+### Phase 7 — minimal fix
+- Patch the true owner/boundary.
+- Avoid unrelated cleanup and symptom-level guards.
+- Re-run regression and relevant broader verification.
+
+### Phase 8 — close evidence loop
+- For performance/memory, re-measure the original path/scenario.
+- For build/platform, rebuild the actual affected target/configuration.
+- Summarize evidence, root cause, fix, and verification.
+
+## Decision points
+
+- Intermittent? Focus on ordering, lifecycle, shared mutable state, retries, and environment timing.
+- Only after incremental action? Investigate invalidation/cache/state transition.
+- Only release build? Inspect optimization/minification/signing/config/runtime differences.
+- Build error? Use first failing task and toolchain versions; read `references/build-failures.md`.
+- Memory grows per repeated flow? Read `references/memory.md` and inspect retained ownership.
+- Jank/latency? Read `references/performance.md` and classify thread/I/O/render/image/query cost.
+- Auth/network? Read `references/networking.md`; distinguish transport, HTTP, session refresh, cache, and ordering.
+- Async/lifecycle? Read `references/async-races.md`.
+- Runtime/state/lifecycle/navigation? Start with the matching `category` row in `data/failure-patterns.csv` and collect its named signals before adding guards.
+- Persistence/database/cache? Capture keys, transaction boundaries, query count, and durable state; do not use cache clearing as diagnosis.
+- Native crash or platform-only failure? Capture symbolicated device logs, variant/toolchain, native boundary, and release artifact evidence.
+
+## Stack detection
+
+- React: `stacks/react.md` for render, state, effect, and external-system boundaries.
+- React Native: `stacks/react-native.md` for JS/UI/native boundaries, lists, images, navigation.
+- Flutter: `stacks/flutter.md` for Dart async, rebuild/layout, raster/UI thread, platform channels.
+- Node: `stacks/node.md` for event-loop, promise/resource/stream/process boundaries.
+- Next.js: `stacks/nextjs.md` for server/client/cache/hydration/build/runtime boundaries.
+- iOS: `stacks/ios.md` for crash/build/signing/lifecycle differences.
+- Android: `stacks/android.md` for Logcat/Gradle/variant/lifecycle/R8 differences.
+- Tauri: `stacks/tauri.md` for Rust commands, webview IPC, capabilities, and bundle/runtime boundaries.
+- Docker: `stacks/docker.md` for image, container, network, volume, and architecture boundaries.
+
+## Failure modes
+
+- Optional chaining/null guards added without explaining why value is unexpectedly absent.
+- Random package/cache clean succeeds once but root cause remains unknown.
+- Multiple changes per experiment make evidence uninterpretable.
+- Debug logging changes timing and is mistaken for a fix.
+- Mock-based test cannot reproduce the real boundary failure.
+- Performance “fix” is judged by feel instead of measurement.
+- Last error line is treated as root cause while earlier failure is ignored.
+
+## Stop conditions
+
+- Stop when the requested outcome is outside this skill and hand off to the more appropriate workflow.
+- Stop before destructive, irreversible, production, credential, publishing, or deployment actions unless the user explicitly approved them.
+- Stop when required evidence is unavailable and proceeding would require guessing about behavior, ownership, or safety.
+- Stop when a repository instruction conflicts with this playbook; repository/user instructions win.
+- Stop when root cause is confirmed by discriminating evidence and the requested fix/verification is complete.
+- Stop earlier if available evidence cannot distinguish remaining hypotheses; report exactly what evidence is missing.
+
+## Escalation conditions
+
+- Ask for device/runtime logs or reproduction data when the failure cannot be observed from repository state.
+- Escalate hardware/OS/service incidents that require unavailable telemetry instead of fabricating diagnosis.
+- Escalate destructive data recovery or credential changes.
+- If the problem expands into independent failures, split them and debug one causal path at a time.
+
+## Verification
+
+- Reproduce original symptom before fix where feasible.
+- Confirm regression test/scenario fails without the causal fix and passes with it.
+- Run relevant suite/typecheck/build/platform target after the narrow proof.
+- Re-measure performance/memory path when that was the symptom.
+- Verify diagnostic logs do not leak secrets and remove temporary noisy instrumentation unless intentionally retained.
+- State any environment/platform not verified.
+
+## Output contract
+
+- **Symptom and reproduction**.
+- **Evidence** — logs/state/timing/build/profiler facts.
+- **Hypotheses tested** — prediction and result.
+- **Confirmed root cause** — causal explanation, not symptom.
+- **Fix** — minimal owning change.
+- **Regression proof** — test/scenario.
+- **Fresh verification** — commands/measurements and remaining uncertainty.
+
+## Anti-patterns
+
+- “Probably X” immediately followed by code edit.
+- Retry/debounce/cache clear as a universal fix.
+- Swallowing error to make UI/build appear healthy.
+- Reinstalling everything without an environment hypothesis.
+- Measuring only after the fix.
+- Claiming root cause from correlation with one log line.
+- Keeping multiple contradictory hypotheses alive after falsification.
+
+## Example
+
+Observation: query result becomes stale only after incremental sync.
+- Evidence: clean index correct; bypass cache correct; cached path stale.
+- Hypothesis: sync fails to invalidate affected query key.
+- Experiment: instrument key/version and bypass/invalidate only that key.
+- Result confirms invalidation path; add regression test that sync updates cached query result.
+- Patch invalidation owner and verify broader query suite.
+- See `examples/evidence-log.md`.

package/skills/showdar-debug/data/failure-patterns.csv

@@ -0,0 +1,34 @@
+id,category,symptom,signals,likely_causes,evidence_to_collect,experiments,common_wrong_fix,verification,severity,tags,reference,stack
+runtime-null,runtime,crash on a user path,stack trace points to property access after input boundary,missing validation or contract mismatch,first frame plus input shape and caller,feed invalid and valid boundary cases,add optional chaining everywhere,regression test rejects malformed input,high,runtime null contract,references/hypothesis-driven-debugging.md,*
+runtime-unhandled,runtime,process exits after rejected work,unhandledRejection or uncaughtException near async task,promise ownership missing or error rethrow lost,process logs with request or job id,await task and observe rejection owner,add a process handler that swallows error,test expected failure and process health,high,runtime async error,references/async-races.md,node
+state-stale,state,UI shows old value after mutation,source read is new but rendered selector/cache remains old,duplicated state or missing invalidation,source snapshot cache key event order,read after mutation with cache bypass,force global refresh after every mutation,mutation then read regression,high,state cache stale,references/async-races.md,react
+state-reset,state,form or screen resets unexpectedly,state changes on remount or key change,unstable identity or effect mirrors props,mount key props and state transition trace,remove key or delay remount to isolate owner,copy props into state and sync in effect,focused interaction test,medium,state lifecycle,references/async-races.md,react
+lifecycle-navigation,lifecycle,crash after navigation,callback fires after screen or controller disposal,uncancelled listener or async completion,route timeline disposal callback and native log,navigate away at each await boundary,add null guards only at visible caller,repeat navigation regression,high,lifecycle navigation,references/async-races.md,react-native
+lifecycle-subscription,lifecycle,duplicate event handling grows per visit,listener count rises after enter leave,subscription not removed or effect dependency repeats,listener registration count and cleanup trace,visit screen twice with event probe,debounce event handler,listener count returns to baseline,high,lifecycle subscription,references/async-races.md,flutter
+race-last-write,race,older request overwrites newer result,request IDs finish out of order,completion order used as freshness,request timeline IDs sequence and state writes,delay first request and release second first,debounce all input,older result is ignored by version or cancellation,high,race ordering,references/async-races.md,react
+race-duplicate,race,action happens twice,duplicate request IDs or two subscriptions,retry plus re-entry or effect double-run,caller count request IDs and lifecycle,trigger rapid action and single action,disable button without server idempotency,one durable side effect exists,high,race duplicate,references/async-races.md,node
+async-timeout,async,request hangs until UI is unusable,no timeout or cancellation event,transport promise never settles or queue is blocked,timing logs and abort signal state,disconnect or hold server response,raise timeout without preserving cancellation,timeout produces actionable retry state,medium,async timeout,references/networking.md,node
+async-cancel,async,cancelled work updates state,cancel event followed by success/error update,abort ignored or stale closure,abort propagation and post-cancel writes,cancel during request and inspect writes,ignore cancellation error globally,disposed owner has no state write,high,async cancellation,references/async-races.md,react-native
+network-transport,network,request never reaches server,offline DNS TLS timeout or connection error,transport environment or endpoint issue,method host class status elapsed and error code,run same request from known network and local host,change HTTP status handling only,transport failure is classified separately,high,network transport,references/networking.md,*
+network-http,network,server returns an error status,HTTP status with valid response body,server contract or auth policy failure,status headers redacted body class and request ID,replay safe request and inspect server route,retry every 4xx,expected status maps to user recovery,high,network http,references/networking.md,node
+network-parse,network,request succeeds but data is unusable,2xx response fails decoder or fields missing,response schema drift or wrong content type,content type status bounded payload shape,save redacted fixture and run decoder,cast response to expected type,decoder rejects bad fixture clearly,high,network parsing,references/networking.md,typescript
+auth-refresh,network,intermittent 401 during refresh,two refresh calls or expired token ordering,refresh race clock skew or retry ordering,redacted token identity request timeline expiry,serialize refresh and compare concurrent behavior,clear session on every 401,one refresh and correct retry behavior,high,auth refresh,references/networking.md,react-native
+cache-key,caching,unrelated users or queries share result,cache keys omit tenant filter locale or parameters,under-specified key or normalization collision,print hashed key components and query inputs,add one distinguishing parameter and compare keys,clear entire cache,distinct inputs produce distinct entries,high,cache key,references/async-races.md,*
+cache-invalidation,caching,updated source is hidden by cached read,write path omits affected key/version,invalid invalidation ownership,source version key and mutation event,disable cache then compare targeted invalidation,global cache clear,affected read changes while unrelated cache survives,high,cache invalidation,references/async-races.md,react
+database-transaction,database,partial state after failure,one table updated while related write fails,transaction boundary split or wrong connection,DB state before after and transaction logs,fail second write and inspect rollback,catch and continue with partial state,atomic state is restored,high,database transaction,references/hypothesis-driven-debugging.md,node
+database-constraint,database,duplicate or invalid row appears,unique or foreign key constraint absent or bypassed,application-only validation race,live schema and concurrent insert trace,run two writers against real DB,check then insert without constraint,constraint or idempotency prevents duplicate,high,database integrity,references/hypothesis-driven-debugging.md,node
+database-n-plus-one,database,latency grows with collection size,query count scales with item count,query in loop or lazy relation,query count timings and row count,compare one item and 100 items,add arbitrary cache,query count follows intended bound,medium,database query,references/performance.md,node
+render-churn,rendering,typing or scroll janks,render count and JS/UI thread work rise,unstable inputs effect loop or broad state owner,profiler flame and render count,freeze unrelated state and profile again,memoize every component,frame budget and render cause improve,high,render performance,references/performance.md,react
+render-hydration,rendering,server and client markup differ,hydration warning or first-paint replacement,environment-dependent render or client-only value,server HTML client value and route phase,replace time/random/browser read with stable input,disable hydration warnings,stable first render then client update,high,hydration mismatch,references/performance.md,nextjs
+navigation-route,navigation,back or deep link lands incorrectly,route params missing or stack differs by entry path,non-serializable params or split navigation ownership,entry URL route state and navigation events,launch cold and warm via deep link,reset whole navigation stack,all supported entry paths resolve correct screen,high,navigation deep link,references/async-races.md,react-native
+memory-list,memory,memory rises after repeated list visits,heap or native image/resource baseline never returns,listener image cache or retained closure,heap snapshots and resource/listener counts,repeat visit with bounded dataset,raise memory limit or force GC only,baseline returns within known tolerance,high,memory retention,references/memory.md,react-native
+memory-cache,memory,cache grows without bound,cache entries and decoded images increase with usage,unbounded cache or missing eviction,cache size hit rate and entry age,load varied keys beyond expected working set,disable caching globally,bounded eviction preserves correctness,medium,memory cache,references/memory.md,*
+cpu-blocking,cpu,interaction freezes during computation,long synchronous task on main or JS thread,parsing loop serialization or crypto on hot path,profile task duration and thread,move one computation off path or chunk it,add arbitrary delay,interaction stays within measured budget,high,cpu event loop,references/performance.md,node
+build-toolchain,build,build fails before source compilation,first tool error names JDK SDK compiler or plugin mismatch,toolchain version incompatibility,exact first error and resolved versions,run supported version matrix,delete caches repeatedly,same target builds with recorded toolchain,high,build toolchain,references/build-failures.md,*
+dependency-mismatch,build,only one package or platform fails,lockfile has duplicated incompatible versions,peer native or transitive mismatch,package tree lockfile and affected importer,resolve one dependency edge and rerun target,force install or delete lockfile,resolved graph and target build are coherent,high,dependency mismatch,references/build-failures.md,package-manager
+ci-only,ci,local passes but CI fails,environment or clean checkout differs,missing secret tool version path or test order,CI command env names cache state and artifact,run clean temp checkout or matching container,skip failing CI test,CI reproduces or difference is documented,high,ci environment,references/build-failures.md,ci
+config-env,environment,works locally but fails in target env,missing or wrong typed config value,configuration precedence or secret injection,variable names only source and effective non-secret metadata,run with variable absent and valid placeholder,print all environment values,missing config fails safely and valid config works,high,configuration environment,references/networking.md,*
+native-crash,native,release app crashes in native path,device log symbolicated frame or signal,platform lifecycle permission ABI or native module mismatch,crash log symbols device OS build and native versions,reproduce on affected device/variant with symbols,catch native error in JS/Dart only,affected release path no longer crashes,critical,native crash,references/build-failures.md,ios
+docker-env-port,environment,Docker service has wrong environment or exposed port,container sees missing config or host cannot reach mapped service port,Compose environment precedence service versus host port mapping or wrong network binding,effective container environment docker compose config port mapping and health endpoint,render the resolved Compose config and test service to service and host paths,rebuild image repeatedly without checking runtime config,Docker service starts with validated config and both expected network paths work,high,configuration environment;docker ports,references/networking.md,docker
+tauri-ipc-permission,native,Tauri frontend command fails or is denied at the IPC boundary,invoke error or capability rejection occurs between frontend and Rust command,command not registered capability permission missing or serialized payload mismatch,frontend invoke payload Rust command registration capability files and desktop logs,call the command with a minimal payload then verify registration capabilities and serialized fields,catch the error only in the frontend or disable permission checks,frontend and Rust command agree on registration permissions payload and failure handling,high,tauri ipc;capabilities permissions;serialization payload,references/build-failures.md,tauri
+android-r8-release,build,Android release build or app fails after R8 minification,release-only missing class method or obfuscated Logcat stack appears for a variant,missing keep rule reflection generated or native class and variant-specific shrinker configuration,Gradle variant R8 warnings mapping.txt missing symbols and comparable debug release behavior,compare the affected release variant with debug inspect mapping and add the narrow keep rule required by evidence,disable minification globally or ship without mapping files,the affected release variant builds and reproduces with symbolicated evidence when needed,high,build toolchain;android r8;proguard release;minification mapping,references/build-failures.md,android

package/skills/showdar-debug/data/index.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "skill": "showdar-debug",
+  "datasets": [
+    {
+      "file": "data/failure-patterns.csv",
+      "idField": "id",
+      "requiredColumns": ["id", "category", "symptom", "signals", "likely_causes", "evidence_to_collect", "experiments", "common_wrong_fix", "verification", "severity", "tags", "reference", "stack"],
+      "searchableFields": ["category", "symptom", "signals", "likely_causes", "evidence_to_collect", "experiments", "common_wrong_fix", "verification", "tags"],
+      "filterFields": ["category", "severity", "stack"],
+      "reference": "references/hypothesis-driven-debugging.md"
+    }
+  ]
+}

package/skills/showdar-debug/examples/evidence-log.md

@@ -0,0 +1,19 @@
+# Example evidence log
+
+Request: search shows the previous title immediately after an incremental sync.
+
+Observation: the bug reproduces only after sync; a clean process is correct.
+Evidence: bypassing the query cache returns the new title, and the database row
+has the new version. The stale response has the old cache version.
+
+Hypotheses:
+1. The index write is stale.
+2. The query cache is not invalidated for the changed document.
+3. Two sync workers race and restore the old value.
+
+Experiment: log document ID, cache key, source version, and worker ID; then
+invalidate only the affected key after the commit. The stale result disappears,
+and reverting invalidation makes the regression test fail again.
+
+Conclusion: cache invalidation is the confirmed root cause. Record the failed
+hypotheses and add a regression test before making the minimal production fix.

package/skills/showdar-debug/references/async-races.md

@@ -0,0 +1,3 @@
+# Async and race failures
+
+Look for stale closures/state, cancellation gaps, duplicate requests, out-of-order responses, lifecycle disposal, shared mutable caches, retry duplication, and missing idempotency. Draw an event timeline with operation ID, owner, start, cancellation, completion, and state write. Reproduce with controlled timing barriers or a fake clock rather than random sleeps. Decide whether correctness requires cancellation, sequence/version checks, serialization, a transaction, or idempotency; debounce is only an input-rate policy, not a general race fix.

package/skills/showdar-debug/references/build-failures.md

@@ -0,0 +1,3 @@
+# Build failures
+
+Start at the first causal error, not the last cascade. Capture command, target/variant, toolchain versions, resolved dependency graph, generated step, configuration, signing/native context, and the first failing task. Compare clean checkout, warm build, and target environment only when each tests a stated cache/environment hypothesis. Preserve logs and mapping/symbol artifacts. Avoid deleting caches, lockfiles, volumes, or generated files until evidence points to corruption and the recovery path is understood.

package/skills/showdar-debug/references/hypothesis-driven-debugging.md

@@ -0,0 +1,3 @@
+# Hypothesis-driven debugging
+
+A hypothesis must predict an observable result: “if H is true, changing X should change Y while Z stays constant.” Rank hypotheses by existing evidence, impact, and cheapness of falsification. Capture reproduction, environment, timestamp, input class, request/state IDs, and expected versus actual result. Change one variable per experiment when practical; use controlled barriers for races. Once evidence contradicts a hypothesis, discard it instead of patching around it. A root cause is confirmed when removing or changing the causal boundary restores the invariant and the regression proof fails without the fix.

package/skills/showdar-debug/references/memory.md

@@ -0,0 +1,3 @@
+# Memory failures
+
+Separate retained objects from transient allocation spikes. Name the repeated user flow, baseline, sample points, heap/native resource view, and tolerance. Inspect ownership/lifecycle of listeners, subscriptions, timers, images, caches, native resources, and large collections. Repeat the flow enough to distinguish warm-up from growth, compare after disposal/idle, and identify the retaining path. Do not “fix” retention by raising limits or forcing collection; bound the owner or dispose the resource and rerun the original scenario.

package/skills/showdar-debug/references/networking.md

@@ -0,0 +1,3 @@
+# Networking failures
+
+Capture method, URL class rather than secret-bearing URL, request identity, status, elapsed time, timeout/cancellation, retry attempt, cache key class, and response parsing result. Distinguish transport failure, HTTP/application failure, auth/session failure, and stale cache. Compare request and server timelines to find retries or out-of-order refresh. Redact tokens, cookies, authorization headers, personal data, and full sensitive payloads. A successful 2xx is not proof that decoding or durable side effects succeeded.

package/skills/showdar-debug/references/performance.md

@@ -0,0 +1,3 @@
+# Performance debugging
+
+Name the user-visible path, workload size, platform, and budget. Classify CPU/thread blocking, render/rebuild churn, layout/raster/GPU work, I/O/network, image decode, memory/GC, database/query, or bundle/startup cost. Record a baseline with the same scenario, then change one causal variable and measure the same metric. Prefer reducing work, moving it off a hot thread, batching, virtualizing, or bounding data over adding arbitrary delays or memoization. Report measurement noise and unverified devices.

package/skills/showdar-debug/scripts/collect-context.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { detectStacks } from './lib/detect-stack.mjs';
+const cwd=path.resolve(process.argv[2]??process.cwd());
+const run=(cmd,args)=>{const r=spawnSync(cmd,args,{cwd,encoding:'utf8'});return r.status===0?r.stdout.trim():null};
+const redact=(s)=>s?.replace(/(token|secret|password|authorization)\s*[=:]\s*\S+/ig,'$1=<redacted>')??null;
+console.log(JSON.stringify({cwd,stacks:await detectStacks(cwd),node:process.version,platform:process.platform,arch:process.arch,gitStatus:redact(run('git',['status','--short'])),gitHead:run('git',['rev-parse','--short','HEAD'])},null,2));

package/skills/showdar-debug/scripts/lib/detect-stack.mjs

@@ -0,0 +1,48 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+async function exists(target) { try { await access(target); return true; } catch { return false; } }
+
+export async function detectStacks(projectRoot) {
+  const found = new Set();
+  try {
+    const names = await readdir(projectRoot);
+    if (names.some((name) => ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb'].includes(name))) found.add('package-manager');
+    if (names.some((name) => ['pnpm-workspace.yaml', 'lerna.json', 'turbo.json', 'nx.json'].includes(name))) found.add('workspace');
+    if (names.some((name) => name.endsWith('.xcodeproj') || name.endsWith('.xcworkspace'))) found.add('ios');
+  } catch { /* inaccessible repository is reported by the caller */ }
+  const packageFile = path.join(projectRoot, 'package.json');
+  if (await exists(packageFile)) {
+    try {
+      const pkg = JSON.parse(await readFile(packageFile, 'utf8'));
+      const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}), ...(pkg.peerDependencies ?? {}) };
+      if (pkg.packageManager) found.add('package-manager');
+      if (pkg.workspaces) found.add('workspace');
+      if (deps.next) found.add('nextjs');
+      if (deps.react) found.add('react');
+      if (deps['react-native']) found.add('react-native');
+      if (deps.vue) found.add('vue');
+      if (deps.svelte) found.add('svelte');
+      if (deps.tailwindcss) found.add('html-tailwind');
+      if (deps.fastify || deps['@fastify/core']) found.add('fastify');
+      if (deps['@nestjs/core']) found.add('nestjs');
+      if (deps['@tauri-apps/api']) found.add('tauri');
+      if (deps.electron) found.add('electron');
+      if (deps.expo || deps['expo-router']) found.add('expo');
+      found.add('node');
+    } catch { /* malformed package is reported by higher-level skills */ }
+  }
+  if (await exists(path.join(projectRoot, 'pubspec.yaml'))) {
+    const pubspec = await readFile(path.join(projectRoot, 'pubspec.yaml'), 'utf8');
+    if (/\bflutter\s*:/m.test(pubspec)) found.add('flutter');
+    found.add('dart');
+  }
+  if (await exists(path.join(projectRoot, 'ios'))) found.add('ios');
+  if (await exists(path.join(projectRoot, 'android'))) found.add('android');
+  if (await exists(path.join(projectRoot, 'Package.swift'))) { found.add('swift'); found.add('spm'); }
+  if (await exists(path.join(projectRoot, 'Cargo.toml'))) found.add('rust');
+  if (await exists(path.join(projectRoot, 'go.mod'))) found.add('go');
+  if (await exists(path.join(projectRoot, 'pyproject.toml')) || await exists(path.join(projectRoot, 'requirements.txt'))) found.add('python');
+  if (await exists(path.join(projectRoot, '.github', 'workflows')) || await exists(path.join(projectRoot, '.gitlab-ci.yml')) || await exists(path.join(projectRoot, 'Jenkinsfile'))) found.add('ci');
+  return [...found].sort();
+}

package/skills/showdar-debug/stacks/android.md

@@ -0,0 +1,21 @@
+# Android debugging
+
+## Apply when
+
+Use this guide for Kotlin/Java, React Native/Flutter native boundaries, Gradle/build, device-only, lifecycle, permission, or release/R8 failures. Record Android API level, ABI, device/emulator, variant, application ID, JDK, Gradle/AGP/Kotlin, and debug versus release-like configuration.
+
+## Architecture and evidence
+
+Separate Gradle configuration/dependency resolution, compile/resource/link, app launch, main-thread/UI, background service, and process-death failures. Capture the first failing Gradle task and full Logcat exception/cause, not only the final “killed” line. Inspect manifest merger output, resources, native ABI, lifecycle callbacks, saved state, and permission result. For release crashes keep the exact APK/AAB, R8 mapping, native symbols, and build IDs so stack traces can be symbolicated.
+
+## Investigation
+
+Reproduce on the affected API/ABI and compare the same variant on a clean install, upgrade install, background/foreground, rotation, and process recreation path. Use StrictMode, Android Studio profiler, frame/rendering tools, and heap/native allocation evidence for performance or memory. For network issues inspect cleartext/TLS, Network Security Config, DNS, timeout, and server correlation. Read `references/build-failures.md`, `references/async-races.md`, or `references/memory.md` when those boundaries are implicated.
+
+## Wrong turns and edge cases
+
+Do not fix a release-only failure by disabling R8, increasing timeouts, or testing only an emulator. Watch for manifest/resource variant drift, exported components, task/launch-mode behavior, Doze/background limits, permission timing, split APK delivery, ABI mismatch, and process death that removes in-memory state.
+
+## Verification
+
+Run the failing Gradle task and affected test, then install the same debug/release-like artifact with `adb`, collect filtered Logcat, and repeat lifecycle/permission paths. Verify mapping/symbol artifacts match the shipped binary and test at least one affected API/ABI class.

package/skills/showdar-debug/stacks/docker.md

@@ -0,0 +1,21 @@
+# Docker debugging
+
+## Apply when
+
+Use this guide for failures that differ between a host and a container, including build, startup, networking, persistence, permissions, health checks, or architecture. Record image digest, base image/runtime, host and target architecture, command/entrypoint, container exit code, and compose/orchestrator context.
+
+## Architecture and evidence
+
+Separate Dockerfile/build-context errors from image/runtime errors. Inspect the effective command, working directory, user, environment variable names (never values), mounts, exposed versus published ports, DNS/resolver configuration, service aliases, health status, and filesystem ownership. Compare `linux/amd64`/`linux/arm64` and libc/runtime assumptions; an image that builds can still fail at startup on the target architecture. Capture the first causal log before the health-check cascade.
+
+## Investigation
+
+Run the exact image digest with a minimal command, then add the entrypoint, dependencies, mounts, and health check one boundary at a time. Verify the process binds to the container interface, not only `localhost`; test service DNS and dependency readiness separately from application health. For volume issues inspect mount path, UID/GID, read-only flags, and existing data without deleting it. Read `references/build-failures.md` for image/build evidence.
+
+## Wrong turns and edge cases
+
+Do not rebuild with a moving tag, delete volumes, or run as root just to make the symptom disappear. Check build secrets versus runtime secrets, PID 1 signal handling, shell-form entrypoints, line endings, CA certificates, timezone/locale, file permissions, port collisions, and health checks that probe an unavailable dependency.
+
+## Verification
+
+Use a pinned image/digest, `docker inspect`, container logs, health output, and an in-network smoke request. Reproduce with the target architecture/runtime and a clean volume when persistence is relevant; confirm graceful stop, restart, dependency outage, and readiness behavior.

package/skills/showdar-debug/stacks/flutter.md

@@ -0,0 +1,21 @@
+# Flutter debugging
+
+## Apply when
+
+Use this guide for Flutter build errors, widget failures, dropped frames, lifecycle races, plugin/platform-channel issues, or memory/image problems. Record Flutter and Dart SDK versions, build mode, device/API level, renderer, and whether the issue is Android, iOS, or both.
+
+## Architecture and evidence
+
+Separate build (widget tree/configuration), layout (constraints), paint (layers), and raster/GPU work. The main isolate handles Dart code and scheduling; platform channels cross into the native runner, while shader compilation and image upload can surface as raster jank. Use Flutter DevTools timeline/frame chart, rebuild indicators, memory snapshots, logs, and Observatory/VM data rather than judging by feel. Capture the widget lifecycle and mounted state around every async callback.
+
+## Investigation
+
+Reproduce with a fixed route/data set and compare first frame, warm navigation, scroll, background/foreground, and rotation where relevant. For rebuild storms inspect provider/Bloc/Cubit scope, selector granularity, inherited dependencies, and `build` side effects. For async work trace cancellation/disposal and distinguish main-isolate CPU work from an isolate boundary. For platform failures capture channel name/payload shape, plugin version, native exception, Gradle/Xcode task, and device logs. Read `references/performance.md`, `references/async-races.md`, or `references/memory.md` as needed.
+
+## Wrong turns and edge cases
+
+Do not move expensive work into `build`, add arbitrary delays, or globally disable animations to hide jank. `const` and rebuild reduction do not fix raster/image cost. Watch for shader warm-up, oversized decoded images, cache growth, hot-reload-only behavior, disposed `BuildContext`, plugin registration differences, and release tree-shaking.
+
+## Verification
+
+Run `flutter analyze`, focused tests, and a profile/release-like build when performance or native integration is involved. Recheck DevTools frame timing, memory after repeated flows, background resume, and both platform runners before claiming resolution.

package/skills/showdar-debug/stacks/ios.md

@@ -0,0 +1,21 @@
+# iOS debugging
+
+## Apply when
+
+Use this guide for Swift/Objective-C, React Native/Flutter native boundaries, build failures, device-only crashes, lifecycle issues, or release-only behavior. Record Xcode/Swift, deployment target, scheme/configuration, device versus simulator, OS version, and debug versus archive build.
+
+## Architecture and evidence
+
+Classify the failure as compile/link, launch/signing, main-thread/UI, background lifecycle, framework/native module, or memory/resource. Capture the first Xcode build error, device Console/crash log, exception type, thread, loaded binary versions, and app state. Symbolicate release crashes with the matching dSYM and binary UUID; an unsymbolicated stack is not evidence for a source-level fix. Check entitlements, privacy usage descriptions, push/background capabilities, and bundle configuration when a feature fails only on device.
+
+## Investigation
+
+Compare simulator/device and debug/archive paths without changing multiple variables. For UI hangs or races inspect main-thread checker, lifecycle callbacks, scene transitions, task cancellation, and actor/thread ownership. For memory pressure inspect Instruments allocations/leaks, image/native resource ownership, and termination reason. For build issues preserve the first failing target/task and resolved Pods/SPM versions; read `references/build-failures.md` and `references/memory.md` when relevant.
+
+## Wrong turns and edge cases
+
+Do not treat a simulator pass as device proof, disable signing/capabilities as a fix, or delete Pods/DerivedData without a cache hypothesis. Watch for release optimization, missing symbols, keychain/secure-storage access groups, permission timing, background suspension, architecture slices, and native crashes that bypass JavaScript/Dart error handlers.
+
+## Verification
+
+Rebuild the affected scheme/configuration, reproduce on the affected OS/device class, inspect symbolicated logs, and run focused tests. For release-only issues validate an archive or equivalent release build plus launch, permission, background/foreground, and crash-observability paths.

package/skills/showdar-debug/stacks/nextjs.md

@@ -0,0 +1,21 @@
+# Next.js debugging
+
+## Apply when
+
+Use this guide for App Router or Pages Router failures involving rendering, routing, data fetching, server actions/route handlers, deployment, or hydration. Name the Next.js version and router because cache and server/client APIs are version-sensitive.
+
+## Architecture and evidence
+
+Locate the execution boundary first: server component, client component, route handler, server action, middleware, edge runtime, or browser. Record route, params, headers/cookies class, build mode, runtime, and whether the failure occurs during `next build`, server startup, request handling, or client hydration. For stale data, distinguish the Data Cache, Full Route Cache, client/router cache, and application cache; capture the key, revalidation policy, tag/path invalidation, and response timestamp.
+
+## Investigation
+
+Compare a static/build-time failure with `next build`, a production request with `next start`, and a client navigation against a fresh load. Inspect server logs and browser console separately. For hydration mismatches compare server HTML with the first client render and look for time, locale, random IDs, browser-only APIs, or different data snapshots. For async races, trace request IDs across server action/API and client transitions. Read `references/async-races.md` and `references/build-failures.md` when those boundaries are involved.
+
+## Wrong turns and edge cases
+
+Do not add `use client`, `dynamic(..., { ssr: false })`, `no-store`, or cache invalidation as a blanket fix. These change execution, caching, or SEO semantics. Environment variables exposed to the browser are build-time inputs in many deployments; changing a runtime secret may not change an already-built client bundle. Check redirects, middleware, streaming/Suspense, error boundaries, and edge restrictions before blaming React.
+
+## Verification
+
+Run `next build` and the production server path when the issue is release-only. Smoke the affected route by direct load and client navigation, assert cache freshness after the intended invalidation, and verify the target runtime has the required Node/edge APIs.

package/skills/showdar-debug/stacks/node.md

@@ -0,0 +1,21 @@
+# Node debugging
+
+## Apply when
+
+Use this guide for Node services, workers, CLIs, and scripts with hangs, latency, crashes, rejected promises, memory growth, or environment-specific behavior. Record Node version, module mode, package manager lockfile, process role, deployment/container image, and the exact command.
+
+## Architecture and evidence
+
+Separate synchronous event-loop work, libuv thread-pool work, worker threads, child processes, and downstream services. Capture request/operation IDs, event-loop delay, CPU/heap samples, active handles, open sockets, connection-pool usage, stream queue sizes, exit code/signal, and the first causal error. For async failures inspect promise ownership and whether the process has an `unhandledRejection`/`uncaughtException` boundary; do not confuse a logged error with a handled operation.
+
+## Investigation
+
+Compare a single request, concurrent load, slow dependency, aborted client, and graceful shutdown. Use a CPU profile/event-loop delay measurement for blocking code, heap snapshots and retained paths for leaks, and stream backpressure metrics for producer/consumer imbalance. Inspect database/network timeout, retry, pool saturation, DNS, TLS, and transaction boundaries. Verify environment/config names and parsed types without printing secret values. Read `references/async-races.md`, `references/networking.md`, or `references/memory.md` for the shared evidence model.
+
+## Wrong turns and edge cases
+
+Do not add retries or increase timeouts before identifying whether the failure is overload, a dead dependency, or duplicate side effects. Avoid synchronous filesystem/crypto/JSON work on request paths when input size is unbounded. Watch for stream listeners that never detach, pools created per request, aborted requests continuing work, ESM/CJS loader differences, and process crashes before request middleware runs.
+
+## Verification
+
+Run the focused test and the production-equivalent start command with the same Node/config shape. Exercise timeout, cancellation, overload, dependency failure, and shutdown paths; verify exit behavior, metrics/log correlation, resource cleanup, and no unhandled rejection warnings.

package/skills/showdar-debug/stacks/react-native.md

@@ -0,0 +1,21 @@
+# React Native debugging
+
+## Apply when
+
+Use this guide for React Native crashes, blank screens, jank, navigation bugs, native-module failures, memory pressure, or issues that appear only on iOS/Android. Record RN, React, Hermes, architecture mode, platform, device/API level, build variant, and whether the repro is debug or release-like.
+
+## Architecture and evidence
+
+Separate the JS thread from the UI/main thread and from native module/JSI execution. Hermes stack traces and heap data describe the JS runtime; Android Logcat, iOS device logs, symbolicated native crashes, and Instruments/Android profilers cover native boundaries. Inspect Metro resolution, transforms, bundle contents, and source maps for packager failures. New Architecture/TurboModules/Fabric can change threading and lifecycle assumptions; do not treat an old bridge workaround as proof of the current path.
+
+## Investigation
+
+For slow interactions, measure JS event-loop work, UI frame time, layout/commit cost, image decode, and native I/O separately. For lists inspect `FlatList`/FlashList windowing, item keys, render identity, measurement, pagination, and image size/cache. For navigation inspect focus/blur, screen mount/unmount, state restoration, and pending async work. For Reanimated, inspect worklets and shared values separately because they execute outside ordinary JS render timing. Check native-module registration and lifecycle on both platforms.
+
+## Wrong turns and edge cases
+
+Do not add `setTimeout`, broad memoization, or disable Hermes/New Architecture just to make a repro disappear. Avoid clearing Metro/Gradle/CocoaPods caches unless cache provenance is the hypothesis. Watch for release-only minification, missing source maps, image memory spikes, process death/background resume, permission prompts, and native crashes before the JS error handler runs. Read `references/performance.md`, `references/memory.md`, or `references/async-races.md` for the causal method.
+
+## Verification
+
+Use Android Logcat and iOS device/simulator logs, then reproduce in the affected variant. Run the repository's Metro/typecheck/test command and a release-like build when packaging or native code is implicated. Confirm the fix across Hermes/architecture and both platforms when the changed boundary is shared.

package/skills/showdar-debug/stacks/react.md

@@ -0,0 +1,21 @@
+# React debugging
+
+## Apply when
+
+Use this guide for browser React components, shared hooks, and client-side state. First classify the failure as render churn, state ownership, effect synchronization, an event boundary, an async race, or an external system. A similar symptom in a server-rendered app also needs `showdar-debug`'s Next.js guide.
+
+## Architecture and evidence
+
+Capture the component tree, props/state identity, effect dependencies, render count, browser console, network timeline, and the exact user action. A render loop is not the same as a state synchronization loop: record which setter runs, which value changes identity, and whether Strict Mode is exposing a non-idempotent effect in development. For context or external stores, inspect provider scope, selector granularity, subscription cleanup, and cache keys rather than only the final value.
+
+## Investigation
+
+Reproduce a fresh mount, prop update, navigation/unmount, and retry path. Use React DevTools Profiler to compare commits and highlight the owner of avoidable renders; use browser performance/network traces for work outside React. For async data, assign an operation ID and test slow, cancelled, and out-of-order responses. Read `references/async-races.md` when completion ordering is relevant.
+
+## Wrong turns and edge cases
+
+Do not silence an effect dependency warning, add broad memoization, or move state upward until the synchronization invariant is explicit. `useMemo`/`useCallback` can hide identity churn without fixing an unstable external input. Watch for stale closures, controlled/uncontrolled transitions, portal ownership, Suspense fallback remounts, and dev-only Strict Mode double invocation.
+
+## Verification
+
+Run the repository's lint/typecheck/test command, then reproduce the original interaction with Profiler/console clean. Verify mount, update, unmount, error, and slow-network paths; compare production mode when the symptom may depend on development-only behavior.

package/skills/showdar-debug/stacks/tauri.md

@@ -0,0 +1,21 @@
+# Tauri debugging
+
+## Apply when
+
+Use this guide for Tauri desktop crashes, blank webviews, command/IPC failures, permissions, packaging, updater, or platform-only behavior. Record Tauri and Rust versions, frontend bundler, target triple, OS, dev versus release bundle, and whether the failure is in the webview or Rust process.
+
+## Architecture and evidence
+
+Separate frontend DOM/runtime errors, Tauri command serialization, Rust command execution, capability/permission denial, webview process crashes, and bundle/signing failures. Capture browser-console output, Rust logs/backtrace, command name and redacted payload shape, capability file, target triple, bundle metadata, and exit/signals. A dev server can hide missing packaged assets, CSP, protocol, resource, or updater problems.
+
+## Investigation
+
+Reproduce the command from the frontend and invoke the Rust implementation with focused tests where possible. Trace request, serialization, permission check, native side effect, and returned error. Compare `tauri dev` with a release bundle installed outside the build tree; inspect resource paths and working-directory assumptions. For native failures use macOS Console/crash reports or Windows Event Viewer, and verify architecture-specific libraries. Read `references/build-failures.md` for build/package evidence.
+
+## Wrong turns and edge cases
+
+Do not grant all capabilities, disable CSP, or use absolute developer-machine paths as a permanent fix. Watch for renamed commands, enum/JSON shape drift, window lifecycle races, updater signature/endpoint mismatch, WebView2/WebKit differences, filesystem permission boundaries, and target-specific path/encoding behavior.
+
+## Verification
+
+Run frontend tests and `cargo test`, then `tauri build` for the affected target. Install the produced artifact on a clean user profile, exercise startup, IPC, filesystem/network permissions, restart, and updater/error paths, and retain symbols/logs for release crashes.