Reproduce

Verify behavior with automation, APIs, logs, and data checks before opening browser DevTools.

Rules

1. Do not ask the user to test until you attempted at least two independent verification paths and reported command outputs.
2. Prefer existing test suite and repo-native scripts first.
3. Prefer CLI/API/log/DB probes over browser inspection.
4. Propose at least three non-DevTools alternatives before escalating to DevTools.
5. If blocked by missing access, request the minimum required access with exact purpose and command.
6. Open DevTools only if non-browser paths cannot observe the behavior.
7. If DevTools is used, include the DevTools Justification block.
8. Finalize with regression protection: add or update tests so the issue is prevented from silently returning.
9. For local-environment bugs, codify seed/restart/env-sync steps in the repo's standard env/bootstrap automation so future runs are one command.

Workflow

1) Discover how the repo is testable

Run fast discovery commands:

rg --files | rg -i '(^|/)(README|Makefile|Justfile|package\.json|pyproject\.toml|go\.mod|docker-compose.*\.ya?ml)$'
rg -n -S 'pytest|vitest|jest|playwright|cypress|e2e|smoke|integration|health|make test|npm run test|pnpm test|uv run pytest'

Select the fastest useful signal in this order:

1. Existing focused test.
2. Existing health/smoke check.
3. Direct API or CLI probe.
4. Log and DB state verification.
5. New minimal regression test.
6. DevTools (last).

2) Run command-first probes

Use references/probe-ladder.md for symptom-to-command mappings.

Minimum bar for "I tested it":

1. One behavior assertion (test/API response/status code/CLI output).
2. One side-effect assertion (log line, DB row/state transition, emitted event, email/job artifact).

Before escalating, list and try multiple ideas from different surfaces:

1. Test surface: run focused existing tests, then add a minimal failing regression test if missing.
2. API surface: replay the flow with curl/CLI and assert response contract.
3. Runtime surface: inspect app, worker, and proxy logs around the event window.
4. Data surface: verify DB/cache/queue side effects directly.
5. Infra surface: health, container state, env wiring, dependency reachability.

3) Use ecosystem checks when available

If the repo has a standard local env/bootstrap entrypoint, use that before asking the user to click around manually. Good candidates include make targets, just recipes, or repo-local scripts such as scripts/dev-status.sh.

If this repo keeps that automation in a sibling workspace, set LOCAL_ENV_ROOT to that path first.

If $dev-sanity is installed, run:

SANITY="$(ls ~/.codex/skills/dev-sanity/scripts/sanity_check.sh ~/.claude/skills/dev-sanity/scripts/sanity_check.sh 2>/dev/null | head -1)"
[ -n "$SANITY" ] && bash "$SANITY" --errors-only

For Google/email workflows, prefer gog plus service logs instead of manual inbox/browser checks.

For local bug closeout, also run the repo's own status/health/wiring entrypoints plus, when available:

[ -n "$SANITY" ] && bash "$SANITY" --health-only
[ -n "$SANITY" ] && bash "$SANITY" --wiring-only

Reference $dev-sanity whenever the issue is local runtime/configuration behavior and that skill is available.

4) Fill gaps instead of punting

If no deterministic path exists, add the smallest regression test or smoke script that proves the fix.

Preferred pattern:

1. Add one failing test reproducing the bug.
2. Implement the fix.
3. Re-run the focused test and nearest related suite.

If still blocked, propose at least three concrete next ideas, each with:

1. Command(s) to run.
2. Expected signal.
3. Why it may isolate the bug.

Example idea set:

1. Add temporary request/response logging around the suspected handler and re-run a curl probe.
2. Replay production-like payload from logs into local API to test parser/validation drift.
3. Run headless E2E from CLI (Playwright/Cypress) before any interactive browser tooling.

5) Access request protocol (before DevTools)

If a better verification path exists but requires access, request it directly instead of jumping to DevTools.

Use this format:

Access Request
- Missing access: <credential/service/env/host/container>
- Why needed: <specific verification goal>
- Command once granted: `<exact command>`
- Expected evidence: <what pass/fail output will show>
- Fallback if denied: <next-best command-first path>

Ask for the minimum needed. Prefer read-only access for verification tasks.

5b) Test accounts from client overlay

Before asking the user for login credentials or cookies, check the active client overlay for test_accounts:

# in skillbox-config/clients/{client}/overlay.yaml → context.test_accounts
test_accounts:
  - id: app-tester
    service: myapp
    email: example@example.com
    password: TestPass123
    role: user
    notes: Default test account

When browser-based or cookie-based testing is needed:

1. Resolve the client overlay (same cwd_match logic as other skills)
2. Look up context.test_accounts for entries matching the target service
3. Use the credentials for API auth (curl -d), cookie acquisition, or headless login
4. If no matching test account exists, use the Access Request protocol above

This avoids interrupting the user for credentials that are already configured. Credentials live only in the client overlay (private, gitignored) — never in the skill itself.

6) DevTools gate (last resort)

Only use DevTools if all are true:

1. Behavior is browser-runtime-only (layout, paint, client-only state, extension-specific issue).
2. No API/log/test/CLI assertion can observe it.
3. At least two non-DevTools probes were attempted first.

When used, report:

DevTools Justification
- Target behavior: <what must be observed>
- Why command-line probes are insufficient: <reason>
- Non-DevTools attempts:
  1. `<command>` -> `<result>`
  2. `<command>` -> `<result>`
- DevTools action: <panel + exact check>
- Evidence captured: <console/network/screenshot/log reference>

7) Regression lock-in (required final step)

When root cause is clear and test coverage is feasible, end by codifying the bug as a regression test.

Required sequence:

1. Write or update a focused test that fails on the buggy behavior.
2. Apply the fix.
3. Re-run the focused test (must pass).
4. Re-run nearest related suite to catch collateral breakage.

If no test can be added, explicitly state why and provide the closest durable alternative (for example: a deterministic smoke script with clear assertions).

8) Local automation lock-in (required for local env bugs)

If resolution required manual seeding, startup ordering, env sync, or restarts, update the repo's local env/bootstrap automation so the same class of bug is faster to catch and recover.

Required sequence:

1. Promote manual local commands into the standard automation entrypoint (typically Makefile, Justfile, or scripts it calls).
2. Ensure seeding and restart flows are idempotent or clearly split into explicit safe targets.
3. Validate from automation entrypoint (not ad-hoc one-off commands).
4. Re-run $dev-sanity checks to verify the loop is healthy.

Preferred path when a separate env workspace exists:

1. Export LOCAL_ENV_ROOT=/abs/path/to/that/workspace.
2. Update that workspace's Makefile, Justfile, or bootstrap scripts when local seed/restart behavior should be standardized.
3. Start/restart using those entrypoints.
4. If $dev-sanity is installed, run bash "$SANITY" --errors-only, --health-only, and --wiring-only.

Do not leave critical local recovery steps as undocumented manual commands in chat output.

Response Template

After verification, reply with:

Verification Summary
- Claim: <what works or fails>
- Commands run:
  1. `<command>`
  2. `<command>`
- Evidence:
  - Assertion: <output/status/log/test evidence>
  - Side effect: <db/log/event artifact>
- Alternatives attempted: <3+ non-DevTools ideas tried or ruled out>
- Access requested (if any): <what was requested and why>
- Regression protection: <failing test added/updated, file path, and pass result; or why not feasible>
- Local automation updates: <Makefile/Justfile/script changes for seed/restart/env sync; or not applicable>
- Dev sanity closeout: <errors/health/wiring results; or not applicable>
- Decision: PASS | FAIL | PARTIAL
- Next command (if needed): `<command>`

If blocked, state exactly what prevented testing and the next concrete command needed to unblock. Do not stop at "please test this" without attempting a path first.