Intuitive Tests

Intuitive Tests

Use this skill to make a test suite easier to understand, faster to run, and less coupled to implementation details. The goal is not "more tests." The goal is a suite where each test has an obvious reason to exist.

Existing tests are not grandfathered in. If a current unit test does not prove project logic, caller-visible behavior, a meaningful failure mode, or a real contract, remove it, merge it into a stronger behavior test, or reclassify it to the correct layer. Treat structure-only, metadata-only, wiring-only, and implementation-shape tests as deletion candidates by default.

The workflow is framework-agnostic, but the examples assume Python/pytest.

Bounded Proposal Rule

For broad or ambiguous cleanup, audit first and stop after a decision-complete proposal. Do not move files, delete tests, rewrite guidance, or edit production code until the target slice, accepted checklist, evidence level, and stop condition are explicit.

For a precise target where the user asks for implementation, apply one coherent vertical slice. Keep newly discovered unrelated ideas parked instead of letting the work expand by drift.

For test-suite cleanup, a good proposal lets the user choose between conservative, layout-first, pruning-first, or fixture-extraction paths.

Verification skips are repo truth, not reusable skill truth. If some tests must not run because of network, credentials, simulator, hardware, paid APIs, or local services, derive the skip from the user's prompt and repo instructions, then report those skipped checks explicitly.

Core Principles

Prefer tests that verify observable behavior through public interfaces.

Unit tests should exercise code logic at the right confidence level: parsing, validation, state transitions, branching, transformations, error handling, fallbacks, and domain rules. They should not exist just to assert static shape: repository layout, file names, file presence, import locations, decorator presence, registration tables, config keys, copied constants, class wiring, or implementation trivia. Those checks belong in contract tests only when packaging, runtime discovery, CLI behavior, plugin registration, schemas, or a documented public artifact actually depends on them.

Avoid tests that only prove:

• dataclass/record fields store values
• a private helper was called
• a constant equals a copied constant
• a file has a particular name
• a file exists, unless packaging or runtime discovery depends on it
• a directory contains a hard-coded list of files
• an import path or module location exists after all in-repo consumers have

migrated to a new layout

• a module imports successfully without exercising behavior
• a decorator, marker, class inheritance edge, registry entry, or config key is

present but no caller-visible behavior changes

• a CLI command, plugin, or route is listed but not invoked through its public

interface

• a mock saw an internal call that does not affect caller-visible behavior
• coverage increased without a meaningful assertion

Organization Taxonomy

Classify tests by the confidence they provide and the cost to run them.

Recommended layers: unit, contract, integration, regression, local, and slow. Keep shared helpers under tests/support/ only after reuse is real.

If the suite is already large and many commands reference exact paths, add markers first. Move files into directories only after the marker split is green and path consumers have been updated.

Modes

| Mode | Use when | Output | Redirect when | | --- | --- | --- | --- | | Audit / propose | The test-suite cleanup target is broad or ambiguous. | Inventory, classification, recommended slice, fallback, verification plan. | The user already selected a precise implementation slice. | | Marker | The approved path is marker-first or directory movement is risky. | Registered markers, marked touched tests, focused collection/tests. | The suite does not need layer selection. | | Layout | The approved path moves tests into a layer-based structure. | Moved classified files, updated path consumers, collection/tests proof. | Path consumers are unknown or the user has not approved movement. | | Prune / consolidate | The target is unnecessary, redundant, or low-signal tests. | Kept/merged/deleted/reclassified tests with behavior proof. | Deletion would remove the last meaningful behavior check. | | Fixture / factory | Repeated setup obscures behavior or appears across tests. | Local fixture/factory extraction with focused tests. | Reuse is speculative. | | Parameterize | Repeated cases differ only by input, expected output, or edge case. | Table-driven tests with readable case ids. | Separate tests give better diagnosis. |

For non-trivial runs, state Selected mode:, Why:, and Redirect: before auditing or editing. For tiny direct changes, one sentence can carry the same information. Add a final Mode note: only when manual invocation, ambiguity, or a better owner matters.

1. AUDIT / PROPOSE mode

Default for broad or ambiguous test-suite refactors.

Inventory test files and current path consumers, classify the suite, identify low-signal tests and setup/table opportunities, then recommend one primary path and one fallback. Stop and ask for the slice unless the prompt already chooses.

Use this decision prompt:

Recommended next slice: 
Why: 
Expected changes: 
Verification plan: 
Tradeoff: 
Please confirm this slice or choose a different one.

2. MARKER mode

Use when the user approves marker-first migration or when directory movement is risky.

Steps:

1. Register markers in pyproject.toml or pytest.ini; prefer

--strict-markers.

1. Add explicit markers to touched tests, or add a temporary transparent

collection hook for legacy flat files.

1. Add runner examples for useful layers such as pytest -m unit and

pytest -m "contract or regression".

1. Run focused collection/tests for the changed layer.

3. LAYOUT mode

Use when the user approves a folder layout migration or explicitly asks to move tests into a layer-based structure.

Steps:

1. Confirm the target layer layout and preserve importability.
2. Move only the classified files in the approved slice.
3. Update path consumers found during AUDIT / PROPOSE mode: CI, recipes,

scripts, docs, hooks, pytest config, and imports.

1. Keep tests/support/ for shared factories and fixtures; avoid making it a

dumping ground for one-off helpers.

1. Delete stale test path wrappers, aliases, or documented old commands after

known consumers are updated unless the user explicitly protects an external contract.

1. Run collection and relevant layer tests. If a check is skipped, cite the user

prompt or repo instruction that made it out of scope.

4. PRUNE / CONSOLIDATE mode

Use when the user approves pruning low-signal tests, or when the requested slice is explicitly about unnecessary unit tests.

Steps:

1. For each candidate, decide whether it protects code logic, caller-visible

behavior, a failure mode, or a real public contract.

1. If it protects a real guarantee, identify the stronger

behavior/contract/regression test that already covers it or should absorb it.

1. Merge one-field-at-a-time tests into behavior tests when that improves

readability.

1. Delete tests that only assert static shape: file names, file existence,

directory shape, import smoke, registry membership, decorator presence, config keys, language mechanics, copied constants, private-call choreography, or stale implementation layout.

1. Reclassify file/artifact checks as contract tests only when they protect

packaging, runtime discovery, CLI output, schemas, report payloads, or documented public artifacts.

1. Keep a short report of what was kept, merged, deleted, or reclassified.

5. FIXTURE / FACTORY mode

Use when repeated setup is the main problem.

Steps:

1. Extract a factory only after repeated dense setup appears in three or more

tests, or when a single setup block obscures the behavior under test.

1. Prefer local fixtures near the tests until reuse is real.
2. Keep factories readable and domain-named; avoid generic "make dict" helpers.

6. PARAMETERIZE mode

Use when repeated tests differ only by input/expected output or edge case.

Steps:

1. Convert repeated cases into table-driven tests.
2. Give each case a readable id.
3. Keep separate tests when setup, behavior, or failure diagnosis meaningfully

differs.

Low-Signal Pruning Checklist

For each candidate test, ask:

• Would a real bug make this test fail?
• Would a harmless refactor make this test fail?
• Is this assertion already covered by a stronger behavior or contract test?
• Is this testing framework/language mechanics rather than project behavior?
• Does this protect a public API, artifact, or compatibility promise?
• Is this only checking a file name, file existence, directory listing, import

path, or stale layout?

• Is this only checking static shape, metadata, registration, wiring, decorator

presence, or private-call choreography?

Actions:

• Keep if it protects safety, parsing, fallback behavior, schema, CLI/report compatibility, or a known regression.
• Merge if several tests assert one behavior one field at a time.
• Delete if it only asserts language mechanics, duplicated implementation

shape, static metadata/wiring, file/path/name trivia, or a stale layout/API that is no longer canonical.

• Reclassify if it is not really a unit test but is valuable as contract or

regression coverage.

• Replace only when deletion would remove the last proof of meaningful

behavior.

Pytest Implementation Notes

For pytest, register custom markers in pyproject.toml or pytest.ini and use --strict-markers. If a temporary pytest_collection_modifyitems bridge is needed for legacy flat files, keep it explicit, boring, and marked with a removal trigger.

Report Format

When applying this skill, report only what changed or what needs a decision:

Target:
Change type:
Classification / recommended slice:
Low-signal tests changed:
Entry points preserved:
Commands run:
Residual risk:
Next safe slice:

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MiaoDX
• Source: MiaoDX/intuitive-flow
• License: MIT

Install and usage instructions live in the source repository linked above.