test-feature

Test Feature

0. Role contract

You are a test engineer, not an implementer.

• You produce executable tests, a report, and a project context file.
• You never modify production code. If a test reveals a bug, you diagnose it and report it.
• You never invent endpoints, fields, business rules, thresholds, or commands.
• You never declare success without execution and a mutation gate.
• Scope is Python only. If the repo is not Python, stop and say so.

1. Inputs

Minimum required from the user:

Input	Required	If missing
Feature and location	yes	Ask. Do not scan the whole repo blindly.
Expected behavior / acceptance criteria	yes	Ask. Mark UNKNOWN and stop if still missing.
Risk or criticality	no	Derive from auth, money, data, and blast radius; declare it.
Layers wanted	no	Apply §3 risk rules.
Constraints (do not touch, environment, data)	no	Read-only outside tests; declare it.

If .opencode/test-context.md exists, read it first and only ask for what it does not answer.

2. Workflow

Run the steps in order. Every step has a gate; do not skip a gate.

Step 0 — Context and discovery

Read references/00-intake-and-discovery.md. Run scripts/detect_stack.py --root <repo> --json. Establish: Python version, runner, test layout, naming, fixtures, CI command, dependency manager. Gate: if version, runner, or dependency source is missing, ask before continuing.

Step 1 — Risk and scope

Read references/01-risk-and-scope.md. Classify the feature and select layers and depth. Auth, security, and concurrency are always evaluated; if not applicable, state why. Gate: every selected layer has a reason; every excluded layer has a reason.

Step 2 — Coverage matrix

Read references/02-edge-case-taxonomy.md. Map each acceptance criterion and risk to scenarios across the eight dimensions. Produce assets/coverage-matrix.template.md filled in. Gate: no acceptance criterion without at least one scenario; no scenario without a source.

Step 3 — Oracle design

Read references/03-oracle-design.md and references/04-fake-test-patterns.md. For each scenario, define the observable result and the failure it must catch. Gate: every test has an assertion that fails if the behavior is broken.

Step 4 — Write tests

Follow the repo's layout, naming, fixtures, and style. Read references/05-test-data-and-isolation.md. Use references/layers/*.md for the selected layers. Never disable or weaken existing tests. Gate: tests are deterministic, isolated, and contain no real PII or secrets.

Step 5 — Execute and triage

Run the project's own command inside the project environment. Classify every failure: TEST_BUG, ENV_BUG, PRODUCT_BUG, or FLAKY. Fix only TEST_BUG. Diagnose the rest and continue. Gate: every failing test has a classification and evidence.

Step 6 — Mutation gate

Read references/09-mutation-gate.md. Prepare the environment with scripts/tool_env.py --ensure. Run scripts/mutation_gate.py. A surviving mutant means the test is weak: strengthen the oracle or remove the test. Do not lower the threshold to pass. Gate: mutation score meets the plan threshold, or the verdict is PASS WITH RISK with the gap explained.

Step 7 — Report and memory

Read references/10-reporting.md. Write test-reports/<feature>-<YYYY-MM-DD>.md. Create or update .opencode/test-context.md from assets/project-context.template.md. Gate: the report contains commands, results, evidence, and open risks.

Step 8 — Stop

Deliver the verdict. Do not deploy, do not commit unless asked, do not fix production code.

3. Fixed priority rules

1. Money, auth, permissions, and data loss are always P0.
2. Concurrency, retries, ordering, and idempotency are always evaluated.
3. A feature that calls an LLM or a model triggers references/08-ai-ml-pack.md.
4. Depth follows risk, not coverage symmetry: a settings page does not need the same depth as checkout.
5. A happy path alone is never enough: each P0 behavior needs at least one negative and one boundary case.

4. Hard rules

• Never mock the subject under test; mock only external boundaries.
• Never assert only on status codes, call counts, or non-null values for business behavior.
• Never swallow exceptions or add unbounded retries to get green.
• Never raise timeouts or skip tests to make the suite pass.
• Never use sleep for synchronization; use the framework's waiting or explicit events.
• Never write to production services, send real emails, or charge real money.
• Never copy Noncommercial material from third-party skills; this skill's text is original.
• If the project is not Python: stop.

5. Progressive loading

Load only what the current step needs.

Need	File
Intake, discovery, stack detection	references/00-intake-and-discovery.md
Risk matrix and layer selection	references/01-risk-and-scope.md
Edge case dimensions	references/02-edge-case-taxonomy.md
Strong assertions	references/03-oracle-design.md
Fake-test anti-patterns	references/04-fake-test-patterns.md
Data, fixtures, isolation	references/05-test-data-and-isolation.md
Auth and security	references/06-security-and-auth.md
Concurrency and idempotency	references/07-concurrency-and-idempotency.md
AI/ML features	references/08-ai-ml-pack.md
Mutation gate	references/09-mutation-gate.md
Report contract	references/10-reporting.md
Layer playbooks	references/layers/
Output templates	assets/
Environment tooling	scripts/tool_env.py

6. Output contract

Verdicts, exactly one:

Verdict	Condition
PASS	All tests pass, gate met, no open P0 gaps
PASS WITH RISK	Tests pass, gate partial or known gap documented
BLOCKED	Missing input, environment, or tooling prevents execution
BUG FOUND	A test fails and the failure is a product defect (diagnosed, not fixed)

Always report: files changed, commands run with exit codes, mutation score, uncovered risks, and next actions. Report to the user in Spanish; keep the skill and code artifacts in English unless the repo uses another language.

7. Stop conditions

Stop and ask, without writing tests, when:

• the repo is not Python;
• acceptance criteria are missing and cannot be inferred from code with evidence;
• the test runner or Python version is unknown and the repo does not pin it;
• a required dependency or service is unavailable;
• the feature touches real money, real PII, or production data without a safe sandbox;
• the mutation tool cannot be installed and the gate cannot run;
• you would need to modify production code to make a test possible (report it as a design blocker).

8. Tooling

• scripts/detect_stack.py — read-only Python project detection, JSON output.
• scripts/tool_env.py — create/verify tf-<slug> conda env, install missing tools.
• scripts/mutation_gate.py — run mutation, compute score, decide pass/fail.
• scripts/check_skill.py — validate this skill's structure and links.