rampstackco/claude-skills

test-case-authoring

Write the test plan and test cases for a single work item: every acceptance criterion traced to a case, each case with test data, steps, an observable expected result, a level, and the evidence a pass must leave behind.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/rampstackco/claude-skills --skill test-case-authoring

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Test Case Authoring

Write the tests for one work item so the QA notes on the ticket have real content and the fix verification on a bug names a real test. Tool-agnostic: works with any test runner, any tracker, and any test management tool.


When to use

  • A story is ready and its acceptance criteria need test cases
  • A bug fix needs a named verification test and a regression set
  • QA notes on a ticket say "test it" and nothing else
  • Checking whether a set of acceptance criteria is testable at all
  • A spike needs an exploratory charter instead of pass/fail cases
  • A coding agent will run the tests and needs to know what evidence to return

When NOT to use

  • Site-wide QA sweeps before a launch or after a deploy (use qa-testing)
  • Writing the acceptance criteria themselves (use ticket-authoring, or pm-spec-writing for the spec behind them)
  • Auditing a whole site for accessibility (use accessibility-audit)
  • Reviewing the code change (use code-review-web)
  • Deciding go or no-go for a release (use launch-runbook)
  • Deciding which items deserve testing effort first (use backlog-triage)

Required inputs

  • The work item: type, title, acceptance criteria or repro steps, QA notes so far
  • The spec or PRD it links to, if any
  • The environments available (local, staging, production-like)
  • The test levels the codebase supports (unit, integration, end-to-end, manual)
  • Known risk areas: what else shares this code path

If the acceptance criteria are not checkable, stop and send them back. Tests written against a vague criterion inherit the vagueness.


The framework: six parts

A test plan is a contract. It says what will be checked, how, at which level, and what a pass leaves behind.

1. From acceptance criteria to tests

Each acceptance criterion maps to at least one test case. Each test case traces back to exactly one criterion or one named risk.

  • An untested criterion is a defect in the plan. Nobody will check it.
  • An untraceable test is a defect too. Either it covers a risk nobody wrote down (name the risk) or it is noise (cut it).

Record the mapping in a traceability matrix. See `references/traceability-matrix-template.md`.

2. Test case anatomy

FieldWhat goes in it
IDStable, unique within the item, e.g., TC-01
TitleWhat is being checked, in a few words
Traces toOne acceptance criterion or one named risk
PreconditionState before step 1: account, role, data, flags
Test dataExact values. "A valid email" is weaker than jordan@example.test.
StepsNumbered, one action each
Expected resultObservable: a value, a message, a state, a status code
EnvironmentWhere it runs
LevelUnit, integration, end-to-end, or manual
Automation statusAutomated, to automate, or manual by design (with reason)

Expected results are observable. "Works correctly" is not a result. "The total shows $42.00 and the order status is paid" is. See `references/test-case-template.md`.

3. Coverage classes

ClassQuestion it answers
Happy pathDoes the main flow work with normal input?
Boundary and edgeWhat happens at limits: zero, one, max, empty, very long, time zones?
Negative and errorWhat happens with bad input, missing permissions, or a failed dependency?
RegressionWhat else uses this code path, and is it still intact?
Accessibility smokeKeyboard reachable, labeled, announced, contrast holds?
Performance smokeDoes it stay within the budget under realistic data?

Mandatory classes depend on the ticket type:

  • Bug: the failing case (the repro, as a test) plus regression. Edge cases from the QA notes when they exist.
  • Story: all six considered. Each class gets cases or a written "not applicable, because."
  • Task: happy path plus regression.
  • Spike: exploratory charters instead of cases.
  • Epic: no cases of its own. Its stories carry them.

See `references/coverage-checklist.md`.

4. Level selection

Pick the lowest level that can observe the expected result.

  • Unit when the result is a return value or state inside one module. Fast, precise, cheap to keep.
  • Integration when the result depends on two or more parts talking: a service and its database, an API and its client.
  • End-to-end when the result is only visible through the full user path: a page, a flow across screens, an email arriving.
  • Manual when the result needs human judgment (visual layout, copy tone, screen reader experience) or the setup costs more than the test is worth. Write the reason.

A price calculation is a unit test, not an end-to-end test that reads the price off the screen. The end-to-end test checks the price appears; the unit test checks the math.

5. Exploratory charters

For spikes, and for stories with real unknowns, write a charter instead of scripted cases.

  • Timebox: 30 to 90 minutes per charter
  • Target: the area to explore
  • Question: what you are trying to learn

Findings are notes, not pass/fail: what you tried, what you saw, what surprised you, what bugs you filed, what new cases to script. See `references/exploratory-charter-template.md`.

6. Evidence

A passing test leaves something behind: a log line, a test runner summary, a screenshot, a recorded run, a response body. The plan names which evidence each case must produce.

A claim of "tested" with no artifact is not a test result. This applies equally to a person and to a coding agent.


Workflow

  1. Read the item. List every acceptance criterion (story), repro and QA note (bug), or definition-of-done line (task).
  2. Check testability. For each criterion, ask: can two people agree on pass or fail? If not, send it back to ticket-authoring with a rewrite proposal.
  3. Name the risks. What else shares the code path, the data, or the screen? Each risk becomes a regression case.
  4. Write cases. At least one per criterion, using the anatomy above.
  5. Fill the coverage classes required for the type. Write "not applicable, because" for any class you skip.
  6. Pick a level per case. Lowest level that observes the result.
  7. Name the evidence each case must produce.
  8. Build the matrix. Confirm every criterion has a case and every case has a trace.
  9. Write the plan. Scope, classes, levels, environments, evidence. See `references/test-plan-template.md`.
  10. Attach to the ticket. The plan summary goes in QA notes. For a bug, the failing-case test goes in fix verification.

Deep dive: tests run by coding agents

When an AI coding agent runs the test plan, the plan has to be written for a reader who will not ask a question and may report success too early.

  • Name the evidence per case. "Paste the runner summary showing TC-01 through TC-06 passed" or "attach a screenshot of the confirmation screen with the order number visible."
  • A tool success message is not evidence. "Command completed" says the command ran, not that the test passed. The agent reads the output back and quotes the line that shows the result.
  • Untestable is a valid result. If an environment is missing, a credential is unavailable, or a case needs human judgment, the agent reports the case as untestable with the reason. It does not mark it passed, skip it silently, or substitute a weaker check.
  • No edits to make a test pass. The agent does not change assertions, expected values, or fixtures to turn red into green unless the plan says the expected value was wrong.
  • Report per case. Pass, fail, or untestable, with the evidence or the reason, for every case ID in the plan.

For how this lands inside an agent brief (the verification section and the stop conditions), see dispatch-authoring.


Failure patterns

  • Cases that restate the criterion. "Verify the user can reset the password." No steps, no data, no expected result. Write the steps.
  • Happy path only. The bug will be in the empty state, the error state, or the boundary. Fill the classes.
  • No test data. "Enter a valid date" gives a different test each run. Name the value.
  • Expected result not observable. "Works as expected," "behaves correctly," "no issues." Name the value, message, or state.
  • Everything marked manual. When a unit or integration test could observe the result, manual is a cost paid every release. Say why it is manual or move it down a level.
  • Bug fix with no regression class. The fix passes its own test and breaks the neighbor. Name what shares the path and test it.
  • Tests with no trace. Cases that map to no criterion and no risk. Trace them or cut them.
  • "Tested" with no artifact. No log, no summary, no screenshot. Not a result.

Output format

For one work item, return:

  1. Test plan summary for the ticket's QA notes: scope, classes covered, levels, environments, evidence
  2. Traceability matrix: criterion or risk to case IDs
  3. Test cases in full, in ID order
  4. Exploratory charters, if any
  5. Gaps: criteria that are not testable as written, with a proposed rewrite

Name files test-plan-[ticket-id].md when saving to disk.


Reference files

from this repository

More skills

All skills
rampstackco
Community

accessibility-audit

Run a comprehensive WCAG accessibility audit covering perceivable, operable, understandable, and robust principles. Use this skill whenever the user wants to audit accessibility, review WCAG compliance, fix accessibility issues, prepare for accessibility certification, address an accessibility lawsuit risk, or systematically improve a site's accessibility. Triggers on accessibility audit, WCAG audit, a11y audit, accessibility compliance, ADA compliance, screen reader test, keyboard navigation, a

1h installs
1
GitHub stars
1.1K
Updated
Nov 8
rampstackco
Community

ads-performance-analytics

How to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid me

1h installs
1
GitHub stars
1.1K
Updated
Nov 8
rampstackco
Community

after-action-report

Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis,

1h installs
1
GitHub stars
1.1K
Updated
Nov 8
rampstackco
Community

analytics-strategy

Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup,

1h installs
1
GitHub stars
1.1K
Updated
Nov 8