showdar-skills 0.2.0

package/skills/showdar-recover/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: showdar-recover
+description: Use when interrupted or partial engineering work must be reconstructed from repository evidence before continuing.
+---
+
+# Showdar Recover
+
+## Purpose
+
+- Recover context after session interruption, compaction, agent failure, crash, or handoff.
+- Distinguish completed-and-proven work from partial, broken, unrelated, and merely claimed work.
+- Prevent duplicate edits or accidental overwrite of user/uncommitted state.
+- Resume from the smallest verified checkpoint.
+- Read `references/interrupted-session.md` and `references/partial-implementation.md` before editing anything.
+
+## When to use
+
+- Agent/task stopped mid-run.
+- New session needs to continue previous repository work.
+- Context was compacted and exact progress is uncertain.
+- Merge/rebase/conflict or failed automation left ambiguous partial state.
+- User asks “where were we?”, “continue from current state”, or “recover this task”.
+
+## When not to use
+
+- Clean new task with no prior partial work.
+- Normal code review or architecture understanding.
+- Do not infer original goal from unrelated git history when user/task context is available.
+- Do not auto-resolve conflicts before understanding both sides.
+
+## Inputs and assumptions
+
+- Repository/worktree state and any task/spec/plan/chat summary available.
+- Git history/status/diff are evidence but may contain unrelated user changes.
+- Previous agent narration is a hint, not proof.
+- `scripts/inspect-state.mjs` performs read-only git-state collection.
+- Fresh tests/builds are needed before classifying a change as proven complete.
+
+## Non-negotiable rules
+
+- Do not edit files until current state and ownership of dirty changes are understood.
+- Never discard, reset, checkout over, or clean uncommitted work without explicit user approval.
+- Classify previous claims by filesystem/test evidence, not trust.
+- Preserve unrelated user changes.
+- Identify last known-good checkpoint and first unverified/broken step.
+- Re-run relevant verification before declaring recovered work complete.
+- Conflict resolution must preserve semantic intent from both sides, not just remove markers.
+
+## Workflow
+
+### Phase 1 — reconstruct goal
+- Read task/spec/plan/commit messages and current conversation context.
+- State the original goal and known constraints in one short block.
+- Mark inferred goal details explicitly.
+
+### Phase 2 — inspect durable state
+- Run `node scripts/inspect-state.mjs <repo>` or equivalent git status/diff/log commands.
+- Identify staged, unstaged, untracked, conflict, generated, and unrelated files.
+- Read partial implementation and tests before editing.
+
+### Phase 3 — classify progress
+- **completed-and-proven**: behavior exists and fresh/reliable proof is available.
+- **implemented-unverified**: code appears complete but proof is absent/stale.
+- **partial**: interfaces/paths incomplete.
+- **broken**: known failing build/test/runtime behavior.
+- **unrelated**: pre-existing/user changes outside recovered task.
+
+### Phase 4 — identify checkpoint and dependency edges
+- Find the smallest coherent completed slice.
+- Identify interfaces later partial work relies on.
+- Read `references/failed-runs.md` when previous automation claimed success/failure inconsistently.
+
+### Phase 5 — choose next safest action
+- Prefer verifying an existing partial/completed slice before writing new code.
+- Resume the first unmet dependency in the original plan.
+- For conflicts, read `references/merge-conflicts.md` and resolve semantics before feature work.
+
+### Phase 6 — re-enter normal workflow
+- If root cause unknown -> showdar-debug.
+- If plan is stale because scope changed -> showdar-plan.
+- If implementation is clear -> showdar-build.
+- If only verification remains -> showdar-test/review as appropriate.
+
+## Decision points
+
+- Dirty file belongs to user/unrelated task? Preserve it and exclude from recovered change surface.
+- Partial interface consumed elsewhere? Verify/finish producer before consumer edits.
+- Previous test output says pass but code changed since? Treat as stale and rerun.
+- Conflict markers present? Resolve merge semantics before continuing task.
+- No git repository? Use filesystem timestamps/task artifacts cautiously and state lower confidence.
+- Original goal ambiguous? Ask user rather than reconstructing from broad history.
+- Conflict markers? Stop feature work; read both sides and base, resolve semantics, then re-run targeted proof.
+- Migration or generated/native state? Freeze destructive actions, identify source-of-truth owner, and verify status before retrying.
+- Only stale narration remains? Treat the task as unverified and use the smallest read-only inspection script plus fresh test.
+
+## Stack detection
+
+- Recovery is stack-agnostic, but detected stack determines which build/test/runtime evidence can prove completion.
+- Mobile changes may require both shared and native project state inspection.
+- Backend changes may include migration/generated schema/job state not obvious from source diff.
+- Web changes may include generated build artifacts that should not be mistaken for source completion.
+- Use repository-native verification commands once task classification is known.
+
+## Failure modes
+
+- Trusting previous agent “done” message without current proof.
+- Running git reset/clean/checkout and destroying user work.
+- Starting new implementation while an earlier dependency is broken.
+- Treating every dirty file as part of recovered task.
+- Resolving conflict mechanically by choosing ours/theirs.
+- Declaring complete because expected files exist.
+- Replanning everything instead of resuming smallest verified checkpoint.
+
+## 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 recovery when goal, current classified state, known failures, and next safest action are clear; then transition to the appropriate execution skill.
+
+## Escalation conditions
+
+- Ask the user when dirty state cannot be confidently assigned to the recovered task.
+- Ask before destructive git operations or dropping generated/user files.
+- Escalate missing external state such as deployment/migration/store actions rather than assuming they happened.
+- If original task context is unavailable and multiple goals fit the diff, request the missing goal.
+
+## Verification
+
+- Re-run status/diff after any recovery edits to confirm unrelated files stayed untouched.
+- Freshly run the tests/builds that prove completed slices.
+- Compare current task state against original plan/spec requirements.
+- Verify conflict markers are gone only after semantic resolution.
+- Confirm next action is dependency-safe and does not redo proven work.
+- State any prior claims that could not be verified.
+
+## Output contract
+
+- **Original goal** — stated vs inferred.
+- **Completed and proven**.
+- **Implemented but unverified**.
+- **Partial**.
+- **Broken / known failures**.
+- **Unrelated protected changes**.
+- **Remaining work**.
+- **Next safest action** with reason and verification needed.
+
+## Anti-patterns
+
+- “Looks mostly done, continue coding.”
+- Trusting task checkboxes without code/test evidence.
+- Cleaning the worktree to simplify analysis.
+- Starting from newest changed file instead of dependency order.
+- Resolving conflicts before reading both sides and tests.
+- Hiding uncertainty about which changes belong to the task.
+
+## Example
+
+Goal: add cache invalidation after sync.
+- Status shows cache helper committed, sync path modified but integration test failing, unrelated README dirty.
+- Classify helper as completed if fresh unit test passes; sync integration as broken/partial; README protected/unrelated.
+- Next action: reproduce integration failure and trace sync invalidation call before editing.
+- See `examples/recovery-report.md`.

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

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "skill": "showdar-recover",
+  "datasets": [
+    {
+      "file": "data/recovery-signals.csv",
+      "idField": "id",
+      "requiredColumns": ["id", "category", "signal", "meaning", "confidence", "action", "evidence", "stop_condition", "tags", "reference", "stack"],
+      "searchableFields": ["category", "signal", "meaning", "action", "evidence", "stop_condition", "tags"],
+      "filterFields": ["category", "confidence", "stack"],
+      "reference": "references/interrupted-session.md"
+    }
+  ]
+}

package/skills/showdar-recover/data/recovery-signals.csv

@@ -0,0 +1,23 @@
+id,category,signal,meaning,confidence,action,evidence,stop_condition,tags,reference,stack
+goal-source,session,task or user request is available,original intent is anchored,high,copy exact goal and constraints into recovery note,task text or issue,stop if multiple goals conflict,goal context,references/interrupted-session.md,*
+plan-source,session,plan/spec has explicit tasks,planned scope is a hint not proof,medium,map each checkbox to current evidence,plan plus files/tests,stop treating checkboxes as completion,plan evidence,references/interrupted-session.md,*
+clean-checkpoint,git,clean status after relevant commit,work may be checkpointed,medium,inspect commit files and rerun tests before resuming,status log commit and tests,stop if commit is unrelated,checkpoint,references/failed-runs.md,*
+dirty-source,git,dirty source with matching failing test,active incomplete implementation,high,read diff and failure before editing,diff and fresh failure,stop if ownership is unclear,dirty work,references/partial-implementation.md,*
+dirty-unrelated,git,dirty file outside task,pre-existing user work,high,protect it and exclude from scope,status diff and task map,stop before broad cleanup,ownership,references/interrupted-session.md,*
+untracked-generated,artifacts,untracked generated output,tool may have run partially,medium,identify source owner and whether artifact is tracked,artifact path timestamps and config,stop before deleting unknown output,generated output,references/partial-implementation.md,*
+conflict-markers,conflict,conflict markers in source,merge or rebase is unresolved,high,read both semantic sides before resolution,marker locations and branch context,stop feature work until resolved,merge conflict,references/merge-conflicts.md,*
+stale-test-log,verification,test log predates current files,recorded result is not current proof,medium,rerun relevant command and compare first failure,log timestamp plus fresh output,stop claiming pass from log,test evidence,references/failed-runs.md,*
+missing-test,test,implementation has no behavior proof,completion is unverified,high,write lowest-level regression before changing more,changed path and invariant,stop before declaring complete,test gap,references/partial-implementation.md,*
+failing-test,test,targeted test fails after partial patch,implementation is broken or fixture is wrong,high,classify failure and trace owning boundary,full failure output and diff,stop broad refactor until cause known,failing proof,references/failed-runs.md,*
+stale-generated,artifacts,generated file disagrees with source,build may use stale output,medium,identify generator then regenerate only owned output,source hash generator command and diff,stop if ownership unclear,stale generated,references/partial-implementation.md,*
+failed-migration,data,migration applied partially,rollback and data safety are uncertain,critical,inspect migration status and backup before app edits,DB status and migration logs,stop before retrying mutation,migration recovery,references/merge-conflicts.md,node
+failed-refactor,source,imports or types broken after refactor,interface migration is incomplete,high,find first compiler/test error and map old callers,compiler output and search,stop before compatibility cleanup,refactor recovery,references/partial-implementation.md,typescript
+missing-consumer,source,new producer exists but caller still old,feature path is incomplete,high,trace producer to all consumers and update contract tests,call graph and fixture,stop if public contract intent unclear,consumer migration,references/partial-implementation.md,*
+partial-native,native,shared code changed without native proof,mobile release may be broken,high,inspect iOS Android or desktop diffs and run narrow platform check,native project status and build,stop release claim without target proof,native recovery,references/partial-implementation.md,react-native
+context-loss,session,chat or agent context is missing,previous narration cannot establish state,high,use durable files logs commits and fresh tests,task docs status diff and tests,stop if goal cannot be reconstructed,context recovery,references/interrupted-session.md,*
+unknown-agent-change,ownership,previous agent changes have no attribution,intent and safety are ambiguous,high,preserve files and audit each changed boundary,diff timestamps tests and surrounding contracts,stop before overwriting,unknown changes,references/interrupted-session.md,*
+recovered-green,verification,fresh targeted and affected checks pass,small slice is proven,high,record command output and move to next unmet dependency,test output and diff,stop only if all requirements mapped,proven slice,references/failed-runs.md,*
+recovered-unverified,verification,code appears complete but no fresh proof,implementation may be correct but cannot be claimed,medium,run exact relevant verification before edit,source plus missing proof,stop completion claim until fresh run,unverified,references/failed-runs.md,*
+safe-next-action,decision,one dependency is clearly next,progress can resume without redoing work,high,perform smallest read/test action that proves boundary,plan dependency and command,stop when action requires user choice,next action,references/partial-implementation.md,*
+destructive-boundary,safety,next action would delete/reset/migrate/overwrite,irreversible risk exceeds inferred authority,critical,ask for explicit approval and preserve evidence,command target and recovery path,stop before destructive action,safety gate,references/interrupted-session.md,*
+recovery-report,output,recovery note has completed partial broken remaining,another engineer can resume without guessing,high,write evidence-backed handoff,report fields and command results,stop once next safe action is executable,recovery output,references/partial-implementation.md,*

package/skills/showdar-recover/examples/recovery-report.md

@@ -0,0 +1,18 @@
+# Example recovery report
+
+Original goal: add cache invalidation after sync.
+
+Durable evidence: the cache-key helper exists and its unit test passes. The sync
+path calls the helper, but the integration test still observes zero invalidations.
+`README.md` has an unrelated user edit and must remain untouched. No conflict
+markers are present; the previous “done” narration is not proof.
+
+Classification:
+- Completed-and-proven: cache-key helper and unit test.
+- Partial: sync commit path and integration proof.
+- Broken: integration expectation currently fails.
+- Protected: unrelated README change.
+
+Next safest action: trace the sync commit path, reproduce the integration test,
+and inspect the invalidation event boundary before editing. Do not reset or
+replay broad history. Completion requires a fresh integration pass.

package/skills/showdar-recover/references/failed-runs.md

@@ -0,0 +1,3 @@
+# Failed agent runs
+
+Treat previous agent narration, task checkboxes, and stale logs as hints, not proof. Verify filesystem, status/diff, current tests, build artifacts, and command exit codes directly. Capture the last fresh successful invariant, first failing command, changed ownership, and uncommitted partial patch before selecting the next action. If a command timed out, re-check its process/authoritative state before restarting.

package/skills/showdar-recover/references/interrupted-session.md

@@ -0,0 +1,3 @@
+# Interrupted session
+
+Reconstruct from durable evidence: exact user goal, task/spec/plan, status/diff/log, recent commits, test results, generated artifacts, and explicit notes. Rank evidence as fresh executable proof, current source/config, durable history, then narration/checkboxes. Do not infer completion from files merely existing. Distinguish intended work from accidental or unrelated dirty state and preserve unknown ownership.

package/skills/showdar-recover/references/merge-conflicts.md

@@ -0,0 +1,3 @@
+# Merge conflicts
+
+Understand both sides and the base before resolving. Preserve semantic changes, tests, generated-source ownership, version/config intent, and migration ordering. Resolve by behavior, not by choosing ours/theirs or merely deleting markers. After resolution, confirm no markers remain, inspect the diff, and run targeted behavior tests plus broader build/type verification for touched boundaries.

package/skills/showdar-recover/references/partial-implementation.md

@@ -0,0 +1,3 @@
+# Partial implementation
+
+Classify each changed area as complete-and-proven, implemented-but-unverified, partial, broken, or unrelated. For each area record owner, changed contract, current consumer state, first failing proof, and next dependency. Verify interfaces before continuing and protect unrelated dirty files. Prefer finishing the smallest coherent slice over opening new fronts; never hide a broken producer behind consumer guards.

package/skills/showdar-recover/scripts/inspect-state.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'; import path from 'node:path';
+const cwd=path.resolve(process.argv[2]??process.cwd()); const run=a=>{const r=spawnSync('git',a,{cwd,encoding:'utf8'});return {ok:r.status===0,out:r.stdout.trim(),err:r.stderr.trim()}};
+const status=run(['status','--short']); const diff=run(['diff','--stat']); const names=run(['diff','--name-only']); const log=run(['log','-5','--oneline','--decorate']);
+console.log(JSON.stringify({cwd,gitAvailable:status.ok,status:status.out||null,diffStat:diff.out||null,changed:names.out?names.out.split('\n'):[],recentCommits:log.out?log.out.split('\n'):[],errors:[status.err,diff.err,names.err,log.err].filter(Boolean)},null,2));

package/skills/showdar-requirements/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: showdar-requirements
+description: Use when product or business input needs explicit behavior, rules, acceptance criteria, assumptions, or open decisions.
+---
+
+# Showdar Requirements
+
+## Purpose
+
+- Convert tickets, briefs, conversations, API notes, and observed repository behavior into implementation-ready requirements.
+- Make behavior, actors, states, rules, constraints, and acceptance evidence explicit without fabricating stakeholder intent.
+- Produce a useful review, story, acceptance-criteria, or requirements-matrix artifact for product, BA, QA, and engineering.
+- Use `data/requirements-patterns.csv` as a searchable prompt and read `references/analysis-guide.md` for deeper analysis structure.
+
+## When to use
+
+- A ticket, BRD, brief, or request is vague, incomplete, contradictory, or difficult to test.
+- The user needs functional/non-functional requirements, user stories, use cases, business rules, acceptance criteria, or a traceability matrix.
+- A flow needs actors, permissions, states, validation, alternate/negative paths, edge cases, or boundary conditions.
+- Repository evidence is needed to distinguish current behavior from requested behavior.
+- A team needs an implementation-readiness verdict and explicit decisions before planning.
+- The final review must state implementation readiness plainly, with blockers rather than implied confidence.
+
+## When not to use
+
+- Do not use this to decide engineering sequencing or file ownership; use `showdar-plan` after the requirement is agreed.
+- Do not use this to discover an unfamiliar repository as the primary task; use `showdar-understand`.
+- Do not implement application code, alter product data, update tickets, or commit changes by default.
+- This skill does not modify application code by default; it produces analysis and documentation artifacts.
+- Do not use this for automated test implementation; use `showdar-test`.
+
+## Inputs and assumptions
+
+- Prefer the original request, source document, ticket identifiers, examples, wireframes, API schemas, current code, models, tests, and observed behavior.
+- Record which statements are directly supplied, which are observed in the repository, and which are assumptions.
+- Preserve domain terminology and existing identifiers; do not create replacement vocabulary without noting the mapping.
+- If a source requirement ID exists, retain it. Create local labels only when needed for traceability and mark them as analysis IDs.
+- State the product context, affected actors, platforms, relevant version, and evidence boundary before deriving behavior.
+
+## Non-negotiable rules
+
+- Separate facts, repository observations, assumptions, decisions required, and recommendations.
+- Separate facts from assumptions before writing recommendations or acceptance criteria.
+- Do not invent business rules, permissions, thresholds, priorities, stakeholder intent, or success metrics.
+- Distinguish must-have behavior from optional, deferred, or out-of-scope behavior.
+- Expose conflicting requirements and missing actors, states, data, error behavior, and ownership.
+- Make acceptance criteria observable and testable; use Given/When/Then when it improves precision, not as ceremony.
+- Identify who can trigger, view, approve, modify, retry, cancel, or recover each important behavior.
+- State evidence and source for repository-derived requirements; never present current implementation as requested product behavior.
+- A bounded assumption is allowed only when it cannot change business meaning; otherwise ask an open question.
+- Present unresolved items under an explicit `Open questions` heading when stakeholder input is required.
+- Do not claim a requirement is ready merely because a happy path is described.
+
+## Workflow
+
+### Phase 1 — establish the source of truth
+
+- Read the supplied material first and quote terminology faithfully in the analysis.
+- Inspect only relevant README, docs, API schemas, types, models, state machines, navigation, flags, validation code, and tests when implementation context matters.
+- Build a source ledger: `source`, `statement`, `kind` (`fact`, `observed`, `assumption`, `open question`), and confidence.
+
+### Phase 2 — decompose behavior
+
+- Identify actor, trigger, precondition, input, system behavior, observable result, postcondition, and failure/recovery behavior.
+- Split functional behavior from non-functional constraints such as latency, availability, privacy, accessibility, localization, auditability, and compatibility.
+- Identify business rules, validation rules, permissions, data ownership, dependencies, constraints, non-goals, and rollout assumptions.
+- Model the happy path, alternate flows, negative flows, edge cases, and boundary values before writing a readiness verdict.
+
+### Phase 3 — check consistency and readiness
+
+- Compare statements for contradictions in terminology, roles, states, timing, data shape, priority, and acceptance evidence.
+- Trace each important requirement to its source, actor, affected surface, and acceptance evidence.
+- Mark unresolved decisions with owner/context when known; do not silently choose between competing interpretations.
+- Classify readiness as `ready`, `ready with explicit assumptions`, or `not ready`; explain the blockers.
+
+## Decision points
+
+- Use a user story when the work is actor/outcome-oriented; use a use case when alternate flows, permissions, or state transitions dominate.
+- Use a requirement matrix when there are multiple actors, surfaces, priorities, or traceability links.
+- Use Given/When/Then for stateful, conditional, or externally observable behavior; use concise assertions for simple rules.
+- Treat an unspecified failure path as a gap, not as permission to choose a fallback.
+- Treat current code as evidence of existing behavior, never as proof that the requested behavior is correct.
+- If a requirement affects native/web/backend surfaces differently, split acceptance by surface rather than hiding platform differences.
+
+## Stack detection
+
+- Web/Next.js: distinguish browser/server/edge behavior, build-time versus runtime configuration, URL/cache semantics, accessibility, and responsive boundaries.
+- Backend/API/Node: inspect request validation, authorization, idempotency, timeouts, persistence, versioned contracts, migrations, and observability.
+- React Native: include permission states, app lifecycle, deep links, OS versions, offline/retry behavior, push flows, and native bridge boundaries.
+- Flutter: include widget/state lifecycle, platform channels, isolates, plugin behavior, generated platform files, and Android/iOS differences.
+- iOS/Android: identify permission prompts, background/foreground transitions, store constraints, OS support, and native configuration.
+- Tauri/Electron: identify frontend/native command boundaries, capability/permission policy, serialization, packaging, and desktop OS differences.
+
+## Failure modes
+
+- Rephrasing a vague request without identifying what is still unknown.
+- Calling an implementation detail a business requirement or treating an existing bug as intended behavior.
+- Writing acceptance criteria that repeat the action but cannot distinguish pass from failure.
+- Omitting denied, expired, duplicate, offline, timeout, cancellation, partial, or concurrent paths.
+- Combining actors or states because the happy path is shorter.
+- Adding invented numeric limits, roles, retention rules, or error messages.
+- Producing a giant matrix with fake precision and no traceable source.
+
+## Stop conditions
+
+- Stop before declaring readiness when a missing decision changes scope, authorization, money/data integrity, safety, or externally visible behavior.
+- Stop before implementation when facts and assumptions cannot be separated from the supplied evidence.
+- Stop when the user asks for source mutation, ticket updates, or release actions; obtain explicit scope or hand off to the appropriate skill.
+- Stop when repository evidence conflicts with the supplied requirement and report both versions.
+
+## Escalation conditions
+
+- Escalate conflicting stakeholder requirements with the exact conflict and the decision owner if known.
+- Escalate missing authorization, data ownership, privacy, compliance, money, deletion, or irreversible-action rules.
+- Escalate a missing platform/version decision when acceptance differs across web, backend, mobile, or desktop.
+- Escalate an implementation-readiness blocker rather than hiding it in a recommendation.
+
+## Verification
+
+- Verify each requirement has an observable result, actor, source/evidence, and relevant failure behavior.
+- Check that acceptance criteria cover happy, negative, alternate, edge, and boundary behavior where applicable.
+- Trace requirements to impacted surfaces, states, data, dependencies, tests, and open decisions.
+- Re-read the final artifact for invented rules, unlabelled assumptions, contradictions, fake IDs, and terminology drift.
+- If repository evidence was inspected, list the exact files or commands used; do not imply execution of tests unless it occurred.
+
+## Output contract
+
+### Requirement review
+
+1. Summary and scope
+2. Known requirements, labelled by source
+3. Missing or ambiguous requirements
+4. Actors, permissions, states, and business rules
+5. Happy, alternate, negative, edge, and boundary flows
+6. Data, dependencies, constraints, assumptions, and out-of-scope items
+7. Risks, conflicts, questions, and decisions required
+8. Traceability and readiness verdict
+
+### User stories and use cases
+
+- Use `As a ... I want ... So that ...` only when it clarifies actor/value.
+- Add preconditions, trigger, main flow, alternate/negative flows, postconditions, and unresolved questions for a use case.
+
+### Acceptance criteria
+
+- Prefer a compact criterion per observable behavior: `Given`, `When`, `Then`, plus examples or boundary values where needed.
+- Include denial, validation, duplicate, timeout, cancellation, offline, and recovery criteria when the requirement implies them.
+
+### Requirement matrix
+
+| ID | Requirement | Type | Priority | Actor | Acceptance evidence | Dependencies | Status/ambiguity |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| source ID or analysis ID | observable behavior | functional/NFR/rule | supplied or unknown | actor/role | testable result | known dependency | ready/gap |
+
+## Anti-patterns
+
+- “The user probably means…” without a labelled assumption or question.
+- Acceptance criteria that say “works correctly” or “is user-friendly” without observable evidence.
+- A plan disguised as requirements: file list, implementation sequence, or chosen library without a source requirement.
+- A repository audit disguised as product intent.
+- Gherkin for every sentence when a short observable rule is clearer.
+- Claiming sign-off, acceptance, or stakeholder agreement that was not supplied.
+
+## Example
+
+**Request:** “Let customers retry a failed transfer.”
+
+- **Fact:** the request names a retry action; it does not define when a transfer is actually failed.
+- **Observed:** the API exposes an idempotency key in `POST /transfers` (source: API schema).
+- **Open question:** can a timed-out request be retried, and who may retry a transfer created by another role?
+- **Acceptance criterion:** Given a transfer is in the documented retryable state, when the authorised actor retries with the same idempotency key, then the system returns the original transfer outcome and does not create a duplicate debit.
+- **Readiness:** not ready until retryable states, authorization, timeout semantics, and user-visible status are decided.

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

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

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

@@ -0,0 +1,11 @@
+id,category,prompt,evidence,output,risk,tags,reference,stack
+functional-decomposition,functional,What actor trigger input and observable result define this behavior?,ticket examples API contract current flow,functional requirement with actor trigger input result and failure behavior,implementation starts from vague prose,functional requirement,references/analysis-guide.md,*
+business-rule,business-rule,Which rule decides eligibility permission amount or state transition?,policy source domain code approval matrix,explicit rule with source owner and unresolved decision,invented policy changes product meaning,business rules,references/analysis-guide.md,*
+acceptance-criteria,acceptance,Can the behavior be proven with observable Given When Then evidence?,test fixtures API response UI state,compact testable acceptance criteria,works correctly cannot distinguish pass from failure,acceptance criteria,references/analysis-guide.md,*
+ambiguity,ambiguity,Which missing or ambiguous requirement has an unspecified actor state timing threshold or error behavior?,contradictory ticket terms missing examples repository mismatch,open question or labelled bounded assumption,team silently chooses incompatible behavior,ambiguity missing decision,references/analysis-guide.md,*
+flow-edge-cases,flow,Which alternate negative edge and boundary flows can change the outcome?,state machine validation limits timeout retry cancellation offline,flow matrix with preconditions and postconditions,happy path hides duplicate partial and recovery defects,negative path boundary state transition,references/analysis-guide.md,*
+state-transition,state,What states and events can this feature enter leave or refuse?,model reducer persistence API tests,state transition table with guards and terminal behavior,invalid transitions corrupt data or confuse UI,state transitions,references/analysis-guide.md,*
+mobile-requirements,platform,Which permission lifecycle deep-link OS and offline behavior is required on mobile?,React Native or Flutter navigation permissions platform tests,platform-specific acceptance split by OS and lifecycle,web assumptions fail on background or denied permission,mobile permissions lifecycle offline,references/analysis-guide.md,react-native;flutter
+api-requirements,platform,Which validation authorization idempotency timeout and compatibility rules cross the API boundary?,OpenAPI types handlers integration tests,API requirement with old-client and failure contract,client and server disagree on retry or error shape,API compatibility idempotency,references/analysis-guide.md,node
+desktop-requirements,platform,What crosses the desktop frontend native command and packaging boundary?,Tauri or Electron commands capabilities serialization,desktop requirement with permission and payload evidence,frontend appears successful while native command rejects,desktop IPC permissions,references/analysis-guide.md,tauri;electron
+non-functional,non-functional,What measurable quality constraint applies to latency availability privacy accessibility localization or compatibility?,SLO accessibility target supported OS browser matrix,non-functional requirement with metric scope and evidence,qualitative non-functional claims cannot be verified,NFR quality constraint,references/analysis-guide.md,*

package/skills/showdar-requirements/references/analysis-guide.md

@@ -0,0 +1,30 @@
+# Requirements analysis guide
+
+Use this reference when a request spans several actors, states, platforms, or source documents.
+
+## Evidence ledger
+
+Keep each statement in one of four buckets:
+
+- **Supplied fact:** directly stated by the user or source document.
+- **Repository observation:** current behavior found in code, schema, config, or tests.
+- **Bounded assumption:** safe working interpretation that does not decide business meaning.
+- **Open decision:** missing stakeholder choice that can change behavior, scope, risk, or acceptance.
+
+Never merge these buckets in a polished summary.
+
+## Flow coverage
+
+For each meaningful action, check:
+
+1. actor and permission;
+2. precondition and current state;
+3. trigger and input validation;
+4. happy result and postcondition;
+5. alternate result, denial, duplicate, timeout, cancellation, offline, and retry behavior;
+6. boundary values, concurrent requests, partial completion, and recovery;
+7. evidence that can prove the result.
+
+## Traceability
+
+Use source IDs when available. Otherwise use a local analysis label and mark it as such. Link each requirement to the affected surface, business rule, acceptance criterion, dependency, and unresolved decision. A matrix is useful only when these links reduce ambiguity.