agentleFS
frostneyfrostney/known-good-route/test-against-spec/SKILL.md

test-against-spec

Skill0 starsChanged 31 days agoUnlicenseView on GitHub

Tests observable behavior against explicit requirements through the real interface. Use when asked to test or verify that a change meets its specification or acceptance criteria, when the user runs /test-against-spec, or when a delivery workflow needs real-interface acceptance evidence.

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Test externally observable outcomes.

    line 32
  2. Distinctive:

    Do not use implementation source, test source, unit tests, mocks, snapshots, or a patch as evidence that behavior works.

    line 38
  3. Distinctive:

    Prefer a preview deployment when it is available and tied to the exact revision under test.

    line 42
  4. Distinctive:

    Use existing black-box automation when it exercises the real delivered interface and its result is current.

    line 45
  5. Distinctive:

    Do not commit, push, deploy, publish, or change external data unless the user separately authorized that action.

    line 47
  6. Distinctive:

    When neither a current preview nor the local environment can reproduce required behavior, report what was attempted and mark the behavior …

    line 65

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Test against spec

Establish whether the delivered behavior matches the explicit specification. Report by default. With the exact fix qualifier, fix observed in-scope gaps and retest them. This skill does not replace source review or the repository's full project gate; the caller owns that aggregate gate, and source review and unit-test success alone are not behavior evidence.

Reuse recorded real-interface evidence when the implementation, requirement, environment, and inputs match, except that fix mode reproduces each failure first-hand before fixing it. Run missing or invalidated behavior checks after changes, failures, or unresolved concerns.

Boundaries

  • Derive expected behavior only from the user request, issue, confirmed mini-spec, product documentation, ADR, or another explicit decision. Never infer it from the implementation. Stop for a material conflict or ambiguity.
  • Test externally observable outcomes. Use the rendered product for user-facing behavior and the real API, CLI, library entry point, job, package, migration, or deployed service for other behavior. For qualitative requirements, compare the actual artifact and behavior with the user's reference or acceptance criteria; passing metrics alone cannot establish visual fidelity or usability.
  • Do not use implementation source, test source, unit tests, mocks, snapshots, or a patch as evidence that behavior works. Requirements with no executable behavior are outside this skill's scope and belong to code review or the project gate.
  • Prefer a preview deployment when it is available and tied to the exact revision under test. Use the local environment when no suitable preview exists or when local execution is needed to cover the current working change. Use existing black-box automation when it exercises the real delivered interface and its result is current.
  • Do not commit, push, deploy, publish, or change external data unless the user separately authorized that action. Use disposable test data where possible and ask before a test would create a material external side effect.

Workflow

  1. Record the specification sources and the exact worktree revision, commit, or preview revision under test. Separate each externally observable requirement from requirements outside this skill's scope, and select the environment for each behavior under the boundaries above.
  2. Exercise every testable requirement. Cover the intended path and the most consequential failure or boundary path. For user-facing changes, interact with the rendered product and cover affected states, accessibility, and relevant viewports.
  3. Record the environment, setup, action or command, input, expected result, and observed result. A requirement passes only when the expected outcome is observed against the exact content under test. A submitted check or acknowledgment without a result leaves the requirement unverified.
  4. When neither a current preview nor the local environment can reproduce required behavior, report what was attempted and mark the behavior unverified.
  5. Without fix, make no edits. With fix, read references/fix-mode.md as soon as fix is present, before inspecting implementation source, and follow it for every failed requirement.

Return a structured summary in the active workflow, not a committed or ignored artifact. Include the tested revision, environments, specification sources, each requirement labeled passed, failed, unverified, or out of scope with its evidence or limitation, fixes and changed files when applicable, and whether any behavior remains failed or unverified.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.