ss-tools/.agents/command/test.related.md

description, handoffs, tools

description	handoffs	tools
Find and run tests related to a specific source file using @RELATION BINDS_TO annotations.	label agent prompt condition Fix Related Test Failures fullstack-coder Fix the test failures in the related tests. The source file that triggered them is: $ARGUMENTS Tests failed label agent prompt condition Add Missing Test Relations semantic-curator Add @RELATION BINDS_TO annotations to connect the source file to its test files. The test selector found no matches for: $ARGUMENTS No related tests found	bash, grep, axiom_search, read

User Input

$ARGUMENTS

Goal

Given a source file path, find and run ONLY the tests that are semantically related to that file. This uses the @RELATION BINDS_TO -> [ModuleName] annotations in test files to trace dependencies.

This is the most efficient verification — avoid running the full suite when only one module changed.

Required Skills

MANDATORY USE skill({name="semantics-testing"}) — BINDS_TO conventions, test contracts. MANDATORY USE skill({name="semantics-contracts"}) — relation syntax, verifiable edit loop.

Execution Steps

1. Identify the source file

$ARGUMENTS should be a path to a source file (e.g., backend/src/plugins/migration.py). If the user provides a directory, pick the most recently modified file or ask for clarification.

2. Run the smart test selector

make test-related F="$ARGUMENTS"

Or directly:

python3 scripts/find-related-tests.py --file "$ARGUMENTS" --verbose --run

This script:

• Extracts module/class names from the source file (#region anchors, class/function defs)
• Searches all test files for @RELATION BINDS_TO -> [ModuleName] annotations
• Returns matching test files with confidence scores (exact > case-insensitive > substring > heuristic)

3. Interpret results

If tests are found and pass: ✅ Report success.

If tests are found and fail: Read the failing test code, identify root cause, handoff to Fix Related Test Failures.

If no related tests found: Two possibilities:

1. The source file genuinely has no tests — report as coverage gap.
2. The @RELATION BINDS_TO annotation is missing from the test file — handoff to semantic-curator for annotation.

4. (Optional) Verify with axiom

If the smart selector found 0 results, try axiom's semantic search as a fallback:

axiom_search operation="trace_related_tests" contract_id="<module_contract_id>"

Output Format

## Related Test Results for `$ARGUMENTS`

### Matched Tests
- [exact] backend/tests/plugins/test_migration_plugin.py (via 'MigrationPlugin')
- [substr] backend/tests/api/test_migration.py (via 'MigrationApi')

### Results
- Total: N | Passed: N | Failed: N
- Time: X.Xs

### Coverage Gap (if no tests found)
- Source file has no linked tests.
- Recommended: create test file with @RELATION BINDS_TO -> [ModuleName]

Constraints

• NEVER run the full test suite as a fallback — only matched tests.
• If the selector finds 20+ related tests, report the count and ask if user wants to run all or narrow scope.
• Heuristic matches (score=0) should be clearly flagged as low-confidence.