showdar-skills 0.2.0

package/skills/showdar-plan/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: showdar-plan
+description: Use when agreed behavior needs a bounded implementation plan, change surface, task order, risks, or verification steps.
+---
+
+# Showdar Plan
+
+## Purpose
+
+- Turn an idea, bug requirement, migration, or design decision into executable engineering work.
+- Make scope and non-goals explicit before code changes begin.
+- Derive tasks from current repository evidence instead of generic software phases.
+- Expose compatibility, data, lifecycle, platform, security, and rollback risks early.
+- Read `references/requirements.md`, `references/scope.md`, and `references/task-decomposition.md` when requirements are ambiguous or the plan is expanding.
+
+## When to use
+
+- New feature or behavior spans multiple files or boundaries.
+- The user explicitly asks for a plan, breakdown, architecture approach, or implementation order.
+- An upgrade/migration needs staged execution.
+- A risky fix needs change-surface and rollback thinking before implementation.
+- Multiple agents/engineers may execute the work and need unambiguous handoff.
+
+## When not to use
+
+- A tiny local edit is already fully specified and planning would add no decision value.
+- The user only wants repository understanding; use showdar-understand.
+- Root cause is unknown; debug first instead of planning a guessed fix.
+- Do not write a long plan merely to satisfy ceremony for a one-line safe change.
+
+## Inputs and assumptions
+
+- The requirement or intended outcome is available.
+- The current repository flow is understood enough to name the real change surface.
+- If not, run showdar-understand first or collect focused context with `scripts/collect-planning-context.mjs`.
+- Existing repository conventions and public contracts are constraints unless the user asks to change them.
+- Plan from current versions/config, not assumed framework behavior.
+
+## Non-negotiable rules
+
+- Every task must correspond to an observable requirement or necessary safety/verification step.
+- State non-goals to prevent scope creep.
+- Name exact files/symbols when repository evidence supports them; otherwise name the boundary and explain uncertainty.
+- Put tests/verification beside the behavior they prove, not in a vague final “add tests” task.
+- Include rollback or staged rollout for irreversible/high-blast-radius changes.
+- Do not invent requirements to make the architecture cleaner.
+- Avoid placeholders such as “handle errors appropriately” without defining the required behavior.
+
+## Workflow
+
+### Phase 1 — normalize the requirement
+- Rewrite the goal as observable behavior.
+- Separate constraints, invariants, preferences, and non-goals.
+- Identify unresolved questions that materially change architecture or scope.
+
+### Phase 2 — anchor to current state
+- Summarize current runtime/data/state flow only as far as the requirement needs.
+- Identify owning boundaries and public interfaces.
+- Record exact current versions/configuration for migrations or platform work.
+
+### Phase 3 — choose an approach
+- Generate at least two viable approaches when trade-offs are real.
+- Compare complexity, compatibility, reversibility, performance, testability, and maintenance.
+- Recommend one and state why it fits this repository rather than a greenfield ideal.
+
+### Phase 4 — define change surface and risk
+- List required changes, possible affected areas, and must-not-change contracts.
+- Use `references/risk-analysis.md` for data/auth/native/concurrency/deployment-sensitive work.
+- Query `data/planning-checklists.csv` through its indexed `category`, `tags`, and `stack` fields before finalizing tasks.
+- For every task include producer/consumer order, compatibility window, rollback boundary, negative path, and exact proof command when those risks apply.
+- Define rollout/rollback or feature-flag needs.
+
+### Phase 5 — decompose execution
+- Order tasks by dependency and independent reviewability.
+- Each task states files/symbols, behavior, error/edge behavior, test, and verification command.
+- Keep task boundaries small enough that a reviewer could approve one and reject the next.
+
+### Phase 6 — self-review
+- Check coverage against every requirement and non-goal.
+- Remove generic steps, duplicated tasks, speculative refactors, and unresolved placeholders.
+
+## Decision points
+
+- Unknown root cause? Stop planning the fix and switch to debugging.
+- One local coherent change? Use a short plan instead of multi-phase decomposition.
+- Public API/schema change? Add compatibility and consumer migration tasks.
+- Data migration? Define expand/migrate/contract or another reversible sequence.
+- Native mobile change? Separate shared code from iOS/Android build/release work.
+- New abstraction? Require a concrete ownership/volatility reason before including it.
+
+## Stack detection
+
+- Detect stack before naming verification commands or platform files.
+- Use `stacks/mobile.md` for lifecycle/native/release concerns.
+- Use `stacks/web.md` for rendering/cache/responsive/accessibility concerns.
+- Use `stacks/backend.md` for contract/persistence/idempotency/rollout concerns.
+- Unsupported stacks follow the same planning contract using repository-specific build/test evidence.
+
+## Failure modes
+
+- Generic sequence: “update code, add tests, verify”.
+- Planning a guessed solution before root cause or current ownership is known.
+- Adding architectural cleanup unrelated to the user outcome.
+- Omitting non-happy paths, migration ordering, or compatibility surfaces.
+- One huge task that spans independent review boundaries.
+- Tests only at the end with no mapping to behavior.
+
+## 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 every requirement maps to an ordered, independently verifiable task and remaining uncertainty is explicitly documented.
+
+## Escalation conditions
+
+- Ask one focused question when an unresolved product/compatibility choice changes the approach.
+- Escalate production data, auth/security policy, billing, or destructive migration decisions to the user.
+- Split the plan when independent subsystems can deliver/test separately.
+- If exact files cannot be named because current state is unclear, return to repository understanding rather than guessing.
+
+## Verification
+
+- Map each stated requirement to at least one task and proof step.
+- Confirm every named command/script exists in the repository or label it as an expected new interface.
+- Check type/signature names for consistency across tasks.
+- Search for vague placeholders and replace them with behavior/commands.
+- Confirm non-goals are not reintroduced by task descriptions.
+- Confirm rollback/compatibility steps exist for high-risk changes.
+
+## Output contract
+
+- **Goal** — one observable outcome.
+- **Non-goals** — excluded adjacent work.
+- **Current state** — task-relevant flow and ownership.
+- **Chosen approach** — with alternatives/trade-offs.
+- **Change surface** — required, possibly affected, must not change.
+- **Risks and dependencies** — including compatibility/rollback.
+- **Ordered tasks** — exact behavior and files/symbols where known.
+- **Verification matrix** — command/scenario proving each task and final result.
+
+## Anti-patterns
+
+- Turning the plan into a restatement of the ticket.
+- Treating folder structure as implementation detail without data/control flow.
+- “Add validation/error handling/tests” without concrete cases.
+- Over-designing abstractions before a second real use exists.
+- Hiding unresolved product decisions inside implementation tasks.
+- Claiming “low risk” based only on small diff size.
+
+## Example
+
+User request: “Add biometric login to the mobile app.”
+- Goal: returning authenticated users can unlock a locally stored session using supported device biometrics.
+- Non-goals: account recovery and server auth redesign.
+- Plan secure storage/session ownership, enrollment state, iOS/Android capability/permission behavior, fallback, tests, and release checks.
+- Split shared session logic from native platform configuration where required.
+- See `examples/feature-plan.md` for the expected shape.

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

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "skill": "showdar-plan",
+  "datasets": [
+    {
+      "file": "data/planning-checklists.csv",
+      "idField": "id",
+      "requiredColumns": ["id", "category", "question", "decision", "evidence", "risk", "tags", "reference", "stack"],
+      "searchableFields": ["category", "question", "decision", "evidence", "risk", "tags"],
+      "filterFields": ["category", "stack"],
+      "reference": "references/requirements.md"
+    }
+  ]
+}

package/skills/showdar-plan/data/planning-checklists.csv

@@ -0,0 +1,25 @@
+id,category,question,decision,evidence,risk,tags,reference,stack
+goal-observable,requirements,What observable outcome proves success?,write a user or system assertion with input and expected result,acceptance scenario or failing test,plan can complete without solving need,goal acceptance,references/requirements.md,*
+goal-metric,requirements,Is success measurable?,name baseline and target or regression threshold,metric query; benchmark; test assertion,qualitative claim hides failure,measurement acceptance,references/requirements.md,*
+goal-actor,requirements,Who performs and observes the change?,identify actor; trigger; output; permission,journey or API caller,wrong owner and missing authorization,actor boundary,references/requirements.md,*
+non-goal,scope,What tempting adjacent work is excluded?,list explicit non-goals and preserve current behavior,issue text plus current callers,scope creep,scope control,references/scope.md,*
+scope-smallest,scope,What is the smallest coherent change surface?,include only files required by behavior and proof,call graph; tests; config,shotgun change,change surface,references/scope.md,*
+scope-deferred,scope,What can remain unchanged?,record safe deferred cleanup with reason,diff and contract review,unrelated refactor expands blast radius,non-goal discipline,references/scope.md,*
+state-owner,architecture,Where does source of truth live now?,name owner and read/write path,store; database; route params; native state,duplicated state diverges,state ownership,references/architecture.md,*
+boundary,architecture,Which layer owns policy?,keep UI; domain; persistence; platform responsibilities explicit,imports and side effects,policy leakage,ownership boundary,references/architecture.md,*
+api-contract,contract,Which public interfaces or schemas change?,write old/new shape and compatibility rule,types; OpenAPI; serializers; consumers,downstream breakage,api compatibility,references/architecture.md,node
+serialization,contract,What crosses process or storage boundaries?,define optionality; errors; versioning,JSON fixtures; wire schema; migration,unknown fields or data loss,serialization contract,references/requirements.md,*
+dependency-runtime,dependencies,Which runtime dependencies are required?,reuse existing package and record version constraint,lockfile and import graph,unplanned install or peer breakage,dependencies,references/risk-analysis.md,*
+dependency-order,dependencies,What must land first?,order producer/schema/config before consumers,dependency graph; task prerequisites,partial interface blocks integration,task ordering,references/task-decomposition.md,*
+rollout,rollout,Can the change be staged?,choose flag; canary; percentage; or atomic release,traffic and feature exposure controls,all users hit unproven path,rollout strategy,references/risk-analysis.md,*
+flag-default,rollout,What is the flag default and owner?,define default; branch behavior; removal condition,config and owner record,permanent hidden branch,feature flag,references/risk-analysis.md,*
+migration-expand,rollout,Can old and new versions coexist?,expand schema/API; deploy compatible reader/writer; migrate; contract,rollback matrix and schema diff,rolling deploy outage or data loss,migration compatibility,references/risk-analysis.md,node
+rollback-boundary,rollout,What is reversible?,name artifact; config; schema and irreversible step,backup; previous artifact; migration status,rollback that cannot run,rollback,references/risk-analysis.md,*
+backward-api,compatibility,Do old clients continue to work?,keep additive or version the contract,consumer versions and contract tests,client outage,backwards compatibility,references/architecture.md,*
+backward-data,compatibility,Can old code read changed data?,preserve defaults and nullable transition,fixture; decoder; old-version test,rollback reads unknown schema,data compatibility,references/risk-analysis.md,*
+test-invariant,verification,Which invariant is proven?,choose lowest effective test level,test case that fails when invariant breaks,tests check implementation only,test strategy,references/task-decomposition.md,*
+test-boundary,verification,Which boundary needs real semantics?,use integration for DB; HTTP; native; cache,ephemeral dependency or contract fixture,mock hides defect,test boundary,references/task-decomposition.md,*
+acceptance-negative,verification,What should fail safely?,include validation; auth; retry; empty; offline; cancellation behavior,negative acceptance cases,silent failure or unsafe fallback,negative path,references/requirements.md,*
+acceptance-observability,verification,How will operation be diagnosed?,define correlation; metric; log/event without secrets,observable field or dashboard,correctness failure becomes opaque,observability,references/risk-analysis.md,*
+platform-native,platform,Which native files/builds are touched?,split shared and iOS/Android/desktop tasks,project files; schemes; flavors,local pass but release failure,native surface,references/risk-analysis.md,react-native
+platform-web,platform,Does server/client or cache ownership change?,define render; URL; freshness; accessibility behavior,route config; browser scenario,hydration/cache regression,web boundary,references/architecture.md,nextjs

package/skills/showdar-plan/examples/feature-plan.md

@@ -0,0 +1,19 @@
+# Example plan shape
+
+Request: add invitation RSVP editing for authenticated hosts.
+
+Current evidence: the host route reads invitation data, the API accepts a full
+payload, and the database already has an `rsvpDeadline`; guests use the same
+read model, so its response shape is a compatibility boundary.
+
+Scope: add a host-only partial update and optimistic UI feedback. Non-goals are
+guest account changes, schema redesign, and replacing the existing form library.
+
+Chosen approach:
+1. Validate the patch at the API boundary and authorize invitation ownership.
+2. Reuse the existing repository update method and invalidate the host query.
+3. Keep the guest read model unchanged and reject edits after the deadline.
+
+Proof per task: authorization integration test, validation test, deadline test,
+cache invalidation test, then typecheck/build. Rollback is a server-side flag
+that hides editing while preserving reads.

package/skills/showdar-plan/references/architecture.md

@@ -0,0 +1,5 @@
+# Architecture choices
+
+Prefer existing repository patterns when they are safe and comprehensible. Introduce a new abstraction only when it creates a real ownership boundary, removes duplicated policy, or isolates volatility. Avoid new layers that only rename calls.
+
+Document public contracts, data flow, state ownership, failure propagation, concurrency, and lifecycle effects. For each boundary state who validates input, who owns side effects, who can retry or cancel, and which test observes the result. Explain why the chosen boundary is safer than nearby alternatives and what is intentionally not changed.

package/skills/showdar-plan/references/requirements.md

@@ -0,0 +1,5 @@
+# Requirements extraction
+
+Translate prose into observable outcomes, constraints, invariants, and non-goals. Separate user-visible behavior from implementation preference. Resolve contradictions before planning. When a requirement is inferred rather than stated, label it and explain the evidence.
+
+A good requirement can be verified. “Improve performance” is not sufficient; define the measured path, current baseline if known, and acceptable result or regression guard. Normalize each item into `actor + trigger + input + observable result + failure/recovery behavior`, and record explicit unknowns instead of filling them with product assumptions.

package/skills/showdar-plan/references/risk-analysis.md

@@ -0,0 +1,5 @@
+# Risk analysis
+
+Classify risk by blast radius and reversibility: data loss, auth/security, public API compatibility, native build/signing, migration, concurrency, performance hot paths, and deployment coupling deserve explicit treatment.
+
+For each high-risk item record affected users or systems, failure mode, detection signal, containment, recovery mechanism, and irreversible step. Check whether old and new readers or writers coexist during rollout. A feature flag is useful only when both branches are tested and its removal owner or event is explicit. For high-risk changes, define rollback before implementation; a one-line schema or permission change can have a large blast radius.

package/skills/showdar-plan/references/scope.md

@@ -0,0 +1,5 @@
+# Scope control
+
+The plan should name the smallest coherent change surface. Include only adjacent refactors required to make the requested behavior safe or testable. Put attractive but unnecessary cleanup in non-goals.
+
+Build a change-surface table with `required`, `possibly affected`, `must not change`, and `verification owner`. Trace callers before editing shared functions, and include generated, native, or config files only when the actual flow proves they participate. For every proposed file or subsystem, answer: what requirement forces this change? If no requirement does, remove it. If it is only future reuse, remove it.

package/skills/showdar-plan/references/task-decomposition.md

@@ -0,0 +1,5 @@
+# Task decomposition
+
+A task is independently reviewable and testable. Sequence tasks by dependency, not by file type. Fold setup into the first task that needs it. Put tests alongside behavior, not in a final generic testing task.
+
+Every task should identify exact files or symbols when repository evidence is available, expected behavior, error and edge behavior, ownership, rollback checkpoint, verification command, and completion evidence. A task is not complete because files exist; its proof must observe the required behavior.

package/skills/showdar-plan/scripts/collect-planning-context.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { access, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { detectStacks } from './lib/detect-stack.mjs';
+const root=path.resolve(process.argv[2]??process.cwd());
+const exists=async p=>{try{await access(p);return true}catch{return false}};
+const files={};
+for(const f of ['package.json','pubspec.yaml','README.md','AGENTS.md']) if(await exists(path.join(root,f))) files[f]=(await readFile(path.join(root,f),'utf8')).slice(0,12000);
+console.log(JSON.stringify({root,stacks:await detectStacks(root),contextFiles:Object.keys(files),snippets:files},null,2));

package/skills/showdar-plan/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-plan/stacks/backend.md

@@ -0,0 +1,3 @@
+# Backend planning
+
+Plan API contracts, persistence and migrations, idempotency, authorization, transactions, retries, queues, observability, rollout, and rollback. Map request and worker lifecycles separately and name health/readiness evidence.

package/skills/showdar-plan/stacks/mobile.md

@@ -0,0 +1,3 @@
+# Mobile planning
+
+Plan lifecycle, navigation, offline/network state, permissions, native integration, device-size and text-scale behavior, platform build files, and release impact when relevant. Separate shared Dart/JavaScript changes from iOS/Android changes. Include back/deep-link/process-death behavior and the device or release build that proves each native requirement.

package/skills/showdar-plan/stacks/web.md

@@ -0,0 +1,3 @@
+# Web planning
+
+Plan rendering boundary, data/cache semantics, responsive behavior, accessibility, browser/server ownership, URL/navigation state, and deployment/runtime constraints. Include loading, empty, error, hydration, metadata, keyboard, reduced-motion, and long-content behavior when UI changes.

package/skills/showdar-quality/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: showdar-quality
+description: Use when planning QA/QC scenarios, risk coverage, regression scope, compatibility checks, or bug-report evidence.
+---
+
+# Showdar Quality
+
+## Purpose
+
+- Decide what should be verified, which risks matter, and what evidence supports acceptance confidence.
+- Produce compact QA scenarios, manual test cases, risk matrices, compatibility plans, regression scope, release checklists, or complete bug reports.
+- Cover behavior beyond automated tests: exploratory, platform, permission, network, data, accessibility, localization, performance, and recovery quality.
+- Use `data/quality-patterns.csv` as a searchable prompt and read `references/qa-guide.md` when a broad verification plan is needed.
+
+## When to use
+
+- QA needs scenarios, manual cases, risk-based coverage, acceptance verification, exploratory charters, or a regression scope.
+- A release needs a platform/browser/device matrix, smoke/sanity checklist, or evidence review.
+- A requirement needs coverage analysis across happy, negative, boundary, state, offline, concurrency, retry, or idempotency behavior.
+- A bug report is incomplete and needs reproducible environment, steps, actual/expected result, evidence, and impact.
+- The user asks what to verify, not how to implement an automated test.
+
+## When not to use
+
+- Do not use this to implement unit, integration, component, or E2E tests; use `showdar-test` for automated test-level selection and code changes.
+- Do not use this as a code/diff defect review; use `showdar-review`.
+- Do not use this as the overall delivery-readiness decision; use `showdar-ship`.
+- Do not mutate application source, production data, test environments, tickets, or release infrastructure by default.
+
+## Inputs and assumptions
+
+- Prefer the requirement, acceptance criteria, change diff, release scope, supported platforms, test evidence, environment, and known defects.
+- Inspect relevant code, schemas, state models, navigation, permissions, existing tests, feature flags, and build metadata when they define observable behavior.
+- Record what was supplied, what was observed, what was executed, and what remains unknown.
+- Treat missing environment/device/network details as a coverage gap; do not invent a passing result or reproduction rate.
+- Use the smallest useful scenario set. Add a case when it covers a distinct risk, boundary, actor, state, platform, or failure mode.
+
+## Non-negotiable rules
+
+- Start from risk and observable behavior, not from a tool or a desired test count.
+- Distinguish planned verification from verification actually executed; showdar-quality does not claim tests ran when they were only planned.
+- Do not invent evidence, device results, severity, reproduction rate, business impact, or acceptance.
+- Cover must-test risks first and label optional/deferred coverage.
+- Include negative, boundary, state-transition, permission, retry, idempotency, offline, and data-integrity checks when the behavior makes them relevant.
+- Do not require every combination; explain omitted combinations and choose representative partitions.
+- Preserve requirement terminology and trace each scenario to a requirement, risk, change surface, or observed defect.
+- If a check belongs inside an automated test, state the boundary and hand implementation to `showdar-test`.
+
+## Workflow
+
+### Phase 1 — define the quality question
+
+- Identify the decision: acceptance, regression confidence, release risk, bug reproduction, compatibility, or exploratory discovery.
+- Identify changed behavior, affected actors, state transitions, data, integrations, platforms, and rollback/recovery concerns.
+- Separate known evidence from assumptions and list missing environment or requirement inputs.
+
+### Phase 2 — map risks and coverage
+
+- Partition behavior into happy, negative, boundary, alternate, state, concurrency, retry/idempotency, and recovery scenarios.
+- Choose an appropriate verification boundary: manual, component, API/integration, native/platform, browser/device, or exploratory.
+- Build a risk-based matrix using likelihood, impact, detectability/evidence, and priority; do not inflate low-value cases.
+- For web/backend/mobile/desktop, identify platform-specific behavior instead of copying a generic checklist.
+
+### Phase 3 — plan and report evidence
+
+- Produce a compact table with preconditions, trigger/steps, expected result, priority, type, and traceability.
+- For regression, separate must-test, high-risk targeted, ordinary targeted, and optional/deferred scope.
+- For a bug, record the environment and evidence exactly; use `unknown` or an open question when data is absent.
+- State what was verified, what was not run, and what evidence is still required for confidence.
+
+## Decision points
+
+- Use smoke testing for a fast build/install/launch/core-path gate; use sanity testing for a narrow change-focused check after a build or fix.
+- Use exploratory testing when the risk is poorly specified or emergent; record a charter, observations, and follow-up cases.
+- Use manual verification for visual, accessibility, permission, lifecycle, and exploratory behavior where automation would miss the risk.
+- Use an automated-test handoff when deterministic regression should live in code; `showdar-test` chooses and implements the level.
+- Use a platform matrix when OS, browser, device class, orientation, permission state, network, or app lifecycle changes behavior.
+- Use boundary testing for minimum, maximum, missing, duplicate, expired, and just-outside-valid inputs when those values change the outcome.
+- Use severity for user/system impact and priority for execution order; do not conflate either with reproduction rate.
+
+## Stack detection
+
+- Web/Next.js: cover browser matrix, responsive breakpoints, keyboard/accessibility, cookies/storage, cache, server/client boundaries, and runtime configuration.
+- Backend/API/Node: cover schema validation, auth roles, timeout/retry, idempotency, concurrency, migrations, compatibility, observability, and data integrity.
+- React Native: cover iOS/Android devices, permission states, cold/warm launch, foreground/background, deep links, offline transitions, push, orientation, and low-memory behavior.
+- Flutter: cover widget states, rebuild/layout/raster risk, isolates, platform channels, plugin behavior, generated files, and Android/iOS integration.
+- iOS/Android: cover supported OS/device range, signing/build flavor, permissions, background behavior, upgrade path, native crashes, and store-relevant configuration.
+- Tauri/Electron: cover native command/capability permissions, serialization, packaging, updater artifacts, and macOS/Windows/Linux differences where supported.
+
+## Failure modes
+
+- Producing hundreds of permutations without prioritizing distinct risk.
+- Calling a test strategy complete because unit tests exist while permissions, data, platform, or recovery paths are unverified.
+- Treating a planned scenario as executed evidence.
+- Using arbitrary sleeps, unstable environments, or vague “works” expectations.
+- Omitting preconditions, data setup, cleanup, account roles, or state reset.
+- Marking a bug non-reproducible without recording attempts, environment, and evidence.
+- Copying a generic mobile/browser matrix without mapping it to supported behavior.
+
+## Stop conditions
+
+- Stop a readiness verdict when acceptance criteria, environment, required devices, data setup, or evidence are missing.
+- Stop before assigning severity when impact or affected users cannot be supported by evidence.
+- Stop before destructive data, production, deployment, or publish actions; this skill plans verification and does not authorize them.
+- Stop when the requested work is automated test implementation and hand off the boundary to `showdar-test`.
+
+## Escalation conditions
+
+- Escalate high-impact data loss, authorization, payment, privacy, security, or migration risks immediately with the evidence and affected surface.
+- Escalate unsupported OS/browser/device combinations rather than treating them as passed.
+- Escalate a blocked environment, missing fixture, unavailable native device, or unreliable test signal.
+- Escalate contradictory requirements to `showdar-requirements` when QA cannot derive a stable expected result.
+
+## Verification
+
+- Every scenario has a meaningful expected result, priority, type, and traceability source.
+- Critical negative, boundary, state, permission, offline, concurrency, retry, and data-integrity risks are either covered or explicitly deferred.
+- Matrix entries are limited to supported platforms and representative partitions.
+- Bug reports contain only observed evidence; unknown fields are labelled rather than guessed.
+- Distinguish “planned”, “executed”, “passed”, “failed”, and “blocked”; attach commands, logs, screenshots, or device details only when available.
+- Re-read the plan for duplicate low-value cases and for gaps hidden by happy-path language.
+
+## Output contract
+
+### Test scenarios
+
+| ID | Scenario | Precondition | Steps/trigger | Expected result | Priority | Type |
+| --- | --- | --- | --- | --- | --- | --- |
+| source or analysis ID | distinct risk/behavior | required state/data | concise action | observable result | P0-P3 or must/high/targeted | manual/automated handoff/exploratory |
+
+### Risk-based matrix
+
+| Area | Risk | Likelihood | Impact | Evidence/coverage | Priority |
+| --- | --- | --- | --- | --- | --- |
+| changed surface | concrete failure | low/medium/high | low/medium/high | scenario, test, or missing evidence | must/high/deferred |
+
+### Regression scope
+
+- **Must test:** acceptance and safety-critical paths.
+- **High-risk regression:** changed boundaries, integrations, permissions, data, state, and platform behavior.
+- **Targeted regression:** nearby behavior with plausible causal impact.
+- **Optional/deferred:** useful coverage blocked by cost or low risk, with reason.
+
+### Bug report
+
+Include `Title`, `Environment`, `Preconditions`, `Steps`, `Actual`, `Expected`, `Repro rate`, `Evidence`, `Impact/severity`, and `Notes`. Preserve unknowns and do not infer missing evidence.
+
+## Anti-patterns
+
+- “Test everything” without partitions, risk, or an execution order.
+- Treating showdar-quality as a replacement for automated test implementation.
+- A test case with no expected result or no reproducible setup.
+- A severity label based only on how often the reporter saw the issue.
+- A release checklist that ignores changed behavior and only repeats build commands.
+- Reporting “QA passed” when only a plan was written.
+- Adding CI/CD, deployment, production data, or release automation to create evidence.
+
+## Example
+
+**Request:** “Create regression scenarios for OTP login.”
+
+- **Must test:** valid OTP within validity window; invalid OTP; expired OTP; wrong account; lockout/rate limit; resend invalidates or supersedes the prior code according to the requirement.
+- **High-risk:** duplicate submit, concurrent verification, app background/foreground, offline during submit, clock skew boundary, localization of errors, and masked destination.
+- **Platform matrix:** supported iOS/Android versions, cold and warm launch, permission/network state only where OTP delivery depends on it.
+- **Expected evidence:** account fixture, timestamps, API response, UI state, logs/correlation ID, and observed device/browser details.
+- **Boundary:** these are QA scenarios. If the user asks to implement deterministic API or UI tests, hand the selected boundary to `showdar-test`.

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

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "skill": "showdar-quality",
+  "datasets": [
+    {
+      "file": "data/quality-patterns.csv",
+      "idField": "id",
+      "requiredColumns": ["id", "category", "question", "evidence", "boundary", "risk", "tags", "reference", "stack"],
+      "searchableFields": ["category", "question", "evidence", "boundary", "risk", "tags"],
+      "filterFields": ["category", "stack"],
+      "reference": "references/qa-guide.md"
+    }
+  ]
+}

package/skills/showdar-quality/data/quality-patterns.csv

@@ -0,0 +1,11 @@
+id,category,question,evidence,boundary,risk,tags,reference,stack
+scenario-partition,scenario,Which happy negative alternate and boundary scenarios can change the outcome?,requirements state model examples,valid invalid missing minimum maximum duplicate and cancelled inputs,happy path misses failure behavior,scenario coverage boundary,references/qa-guide.md,*
+risk-based,risk,Which changed area has the highest likelihood and impact?,diff dependency data and incident history,prioritize authorization data integrity integration and recovery,uniform checklist hides critical risk,risk based testing,references/qa-guide.md,*
+regression-scope,regression,What must high-risk targeted and optional regression cover?,change surface release notes known defects,changed boundaries plus adjacent behavior with explicit deferrals,release confidence is not tied to change,risk regression scope,references/qa-guide.md,*
+platform-matrix,compatibility,Which OS browser device locale orientation and lifecycle partitions matter?,support matrix feature behavior native config,representative supported partitions not every combination,platform defect escapes desktop-only verification,device browser platform matrix,references/qa-guide.md,react-native;flutter;ios;android
+network-offline,network,What happens across offline timeout reconnect retry and duplicate submission?,API contract logs state transitions,assert user state data integrity and idempotency after recovery,network transitions create duplicate or lost effects,offline retry idempotency,references/qa-guide.md,node;react-native;flutter
+permission-lifecycle,platform,What should happen for denied limited revoked and background permission states?,permission API navigation lifecycle evidence,verify explain recover and re-entry behavior per platform,permission denial traps the user,permissions lifecycle,references/qa-guide.md,react-native;ios;android
+accessibility-localization,quality,Which keyboard screen-reader text-scaling locale and formatting checks apply?,semantic roles snapshots locale fixtures,verify names focus errors order truncation and translated meaning,visual pass hides inaccessible or broken localized flow,accessibility localization,references/qa-guide.md,react;react-native;flutter
+data-concurrency,data,How are concurrent retry and partial operations kept consistent?,transaction logs idempotency keys controlled interleavings,assert no duplicate loss or impossible state,serial-only testing misses races,data integrity concurrency,references/qa-guide.md,node
+bug-reproduction,bug-report,What environment preconditions steps actual expected and evidence make this defect reproducible?,logs screen recording build and account details,record unknown fields and repro attempts without guessing,weak report cannot be triaged,bug reproduction evidence,references/qa-guide.md,*
+release-qa,release,What smoke sanity acceptance and rollback-adjacent checks are required before handoff?,release scope build metadata test results,verify artifact and critical path without implying deployment,ship checklist claims unexecuted confidence,release QA smoke sanity,references/qa-guide.md,*

package/skills/showdar-quality/references/qa-guide.md

@@ -0,0 +1,20 @@
+# QA planning guide
+
+Use this reference to keep a QA plan small but risk-complete.
+
+## Risk partitions
+
+Prioritize changed boundaries, high-impact data, authorization, state transitions, external integrations, platform differences, and recovery. Partition inputs into valid, invalid, missing, minimum, maximum, duplicate, stale, concurrent, offline, and cancelled cases only when each can produce a distinct outcome.
+
+## Evidence vocabulary
+
+- **Planned:** scenario exists but was not run.
+- **Executed:** command/device/environment and result are recorded.
+- **Passed/failed:** an executed check has observable evidence against its expected result.
+- **Blocked:** required environment, fixture, device, permission, or dependency was unavailable.
+
+Never turn planned coverage into a pass claim.
+
+## Platform matrix
+
+Choose supported partitions rather than every device. Record OS/browser version, device class, orientation, permission state, network transition, app lifecycle, locale, and build flavor when those dimensions affect behavior. For native apps include cold/warm launch, background/foreground, upgrade, and low-memory checks when the feature touches lifecycle or resources.