test-scribe

Test Scribe — Test Pharaoh Orchestrator

If you are running as a subagent: STOP

This skill (test-pharaoh:test-scribe) runs only in the main Claude Code session. It coordinates three review gates (feature understanding, plan review, escalation) that require direct user interaction — those gates cannot function from a subagent context.

If you were dispatched as a subagent via the Agent tool — by another plugin, by a workflow coordinator, or even by one of this plugin's own subagents (architect, mason, physician) — STOP now. Return to your caller with:

/test-scribe must be invoked from the main session (it requires interactive review gates). Please exit this subagent and invoke /test-scribe directly, or narrow your request to a specific subagent task.

Do not execute the workflow below from within a subagent.

---

You are the orchestrator for the test-pharaoh plugin. When the user invokes /test-scribe, follow this workflow in order. Do not skip gates. Do not deviate from the project's existing conventions.

---

Preflight

Before starting the workflow, verify these prerequisites. If any fails, stop with a clear message — do NOT proceed into Step 1.

• The extractor jar must exist at <plugin-dir>/scripts/kotlin-signatures/build/libs/kotlin-signatures.jar. If it's missing (fresh install, or post-/plugin update which wipes build/), build it yourself before continuing:

  (cd <plugin-dir>/scripts/kotlin-signatures && ./gradlew shadowJar)
  

  Tell the user you're doing a one-time ~30s build of the signature extractor. Requires JDK 17+. If the build fails (e.g., JDK not installed, no network for first-time Gradle dependency fetch), stop and report the error with a prompt for the user to install JDK 17+ or re-run with network access.
• The wrapper script <plugin-dir>/scripts/kotlin-signatures/bin/kotlin-signatures is executable (test -x). If not, tell the user to chmod +x it.
• The current working directory is inside a git repo (git rev-parse --is-inside-work-tree). If not, stop — /test-scribe only operates on a branch.

Branch / worktree selection

Before collecting the story + ACs, ask the user where tests should be written:

• (a) Current branch — work on the branch already checked out. Generated tests land here. Pick this if you already have a feature branch ready.

• (b) New branch — create a new branch off HEAD. Suggest a name based on the feature (e.g., tests/<feature-slug>); let the user override. Run: git checkout -b <name>.

• (c) Worktree — create an isolated git worktree so the user's current workspace is untouched. Do this inline; do not invoke any other skill.

  1. Pick a worktree parent directory. Prefer existing .worktrees/ at the repo root; otherwise existing worktrees/; otherwise default to creating .worktrees/.
  2. Verify the parent is gitignored — probe with git check-ignore -q <parent>/probe. If not ignored, add the dir to .gitignore and commit that change BEFORE creating the worktree; otherwise generated content may leak into the user's git history.
  3. Ask the user for a branch name. Suggest tests/<feature-slug> based on the story title; accept overrides.
  4. Create the worktree: git worktree add <parent>/<dir-safe-name> -b <branch-name>. Replace / with - in the directory path only; keep the branch name as-is.
  5. cd into the new worktree. Continue to Step 1 from there.

Do not proceed to Step 1 until the user has picked one and, for (b)/(c), confirmed the branch name.

1. Collect inputs

• Inputs from the user:
  • User story + acceptance criteria (required). If the user invoked /test-scribe with these inline, use them; otherwise stop and prompt. Never continue with a blank or inferred spec.
  • Any other relevant context (optional) — design decisions, product intent, edge cases the user wants emphasised, links to prior discussions or PRs. Weave into Gate 0 reasoning and plan synthesis. Do not prompt for it if not offered; just accept it when given.
• Determine the parent branch:
  1. Read .claude/test-pharaoh/config.json. If parentBranch is set, use it.
  2. Otherwise, check for local branches develop, main, master (in that order). Use the first one that exists.
  3. If none found, ask the user and persist to config.json.
• Compute the diff: git diff <parent>...HEAD (three-dot syntax — commits unique to this branch).

2. Discovery (cached)

• Hash gradle/libs.versions.toml (SHA-256). If .claude/test-pharaoh/project-profile.json exists AND its versionCatalogHash matches, reuse it.
• Otherwise dispatch the architect subagent with the repo root as input. It writes a fresh profile.
• If no libs.versions.toml exists, the discoverer falls back to scanning build.gradle.kts files; if still nothing, prompt the user to confirm a minimal profile and proceed.
• Read the profile once done.

3. Scope

• If the diff is non-empty: scope = (classes changed in diff) ∩ (classes implicated by ACs). "Implicated by ACs" means concepts named in ACs whose matching class appears in the diff — be conservative.
• If the diff is empty: run AC-based inference. Scan modules named/implied in the ACs (NOT the whole repo) for classes whose name or KDoc matches AC concepts. Present the candidate list to the user; they confirm, edit, or replace. If the final list is empty, stop with "no scope — nothing to test."

4. Signature extraction

• For each class in scope, invoke the bundled extractor:

  <plugin-dir>/scripts/kotlin-signatures/bin/kotlin-signatures <path/to/Class.kt>
  

• Save each extract to .claude/test-pharaoh/runs/<timestamp>/extracts/<mirror-path>/<Class>.kt.
• If extraction fails (syntax error, Java file, unknown parse error), mark that class in the plan as EXTRACTOR FAILED — write tests for <Class> manually. Do NOT fall back to reading the body.

5. GATE 0 — Feature understanding

Write a short inline summary (3–5 bullets) covering:

• What the feature does (one-sentence goal).
• Who uses it / when it fires.
• What the ACs collectively imply beyond their literal text.
• Which classes / subsystems are touched.
• Any ambiguities you cannot resolve from inputs alone.

Ask: "Does this match what you intended? Anything I missed or misinterpreted?"

Loop until the user confirms. Only then proceed. Foundational misunderstandings caught here are cheap; at later gates they cost plan synthesis or generated tests.

6. Plan synthesis

For each class in scope and each applicable tier (unit, integration, roborazzi, cucumber), list the planned tests with traceability markers. Example format in .claude/test-pharaoh/runs/<timestamp>/TEST_PLAN.md:

### com.sample.auth.LoginViewModel (tier: unit)

- [ ] onSubmit_validCreds_emitsSuccess
      source: AC-1
- [ ] onSubmit_invalidCreds_emitsInlineError_andClearsPassword
      source: AC-2
- [ ] onSubmit_networkFailure_emitsBanner
      source: AC-3 + catalog/retrofit.md#network-failure
- [ ] onSubmit_5xx_emitsGenericError
      source: AC-4 + catalog/retrofit.md#5xx
- [ ] sealedStateBranches_exhaustivelyRendered
      source: contract (LoginUiState sealed branches)

Additionally:

• Attach any clarification questions (things contract + catalog leave ambiguous).
• If existing tests rely on mocks, add a refactor proposal section offering to migrate them to fakes before writing new tests.
• If the project profile detected a framework but no matching catalog/<framework>.md exists in the plugin, add a plan annotation: UNKNOWN: no catalog for <framework>; AC + contract only. The user can add a catalog file mid-flow or accept the narrower coverage.

7. GATE 1 — Plan review

Tell the user the plan is written. They review, edit TEST_PLAN.md directly if they want, or answer clarifying questions. Do not dispatch the generator until the user approves.

8. Generate

For each approved (class × tier), dispatch a mason subagent in parallel where independent. Inputs to each:

• signatureExtract: path to the extract for this class.
• tier.
• catalogPaths: catalog entries matched by profile frameworks × class imports/types visible in the extract.
• planExcerpt: the relevant slice of TEST_PLAN.md.
• projectProfilePath.
• existingTestPaths and existingFakePaths for this class (read-allowed).

Aggregate the generator results. If any returned clarification requests, resolve them with the user and re-dispatch.

If a generator returns a context-limit error (the class under test is too large for the signature extract + catalog + plan excerpt to fit), split the work for that class — either by tier (dispatch one generator per tier) or by method (generate tests for a subset of methods at a time) — and redispatch. Do not skip the class silently.

9. Run and triage

For each module where tests were written, run the module-scoped task(s) from the profile:

./gradlew <module>:<task>

(Use profile.modules[module].testTasks mappings — e.g., unit → :test, roborazzi → :verifyRoborazziDebug, instrumented → :connectedDebugAndroidTest.)

If any instrumented tests were written, check adb devices first; if no device/emulator is connected, prompt the user to start one or skip the instrumented tier.

Capture output to .claude/test-pharaoh/runs/<timestamp>/run.log.

Apply a per-Gradle-task timeout (default 5 minutes). If a task hangs past the timeout, kill it and escalate directly to Gate 2 — do not retry a hung task, and do not loop-guard on hang (it's immediately substantive).

If there are failures, dispatch physician:

• For mechanical results, apply the returned patches and re-run. Retry limit: ≤2 retries per failing test. The limit applies per test, not globally, so a run with many mechanical failures can accumulate more than 2 total retries across the suite.
• Loop guard: if the same test fails with the same error after a patch, escalate directly without retrying.
• Substantive results go straight to Gate 2.
• If a mechanical patch fails to apply (conflict with a file the user edited mid-run), escalate that test to Gate 2 with the patch and the conflict details so the user can resolve manually.

10. GATE 2 — Escalation (on persistent failure)

Write diagnosis.md under .claude/test-pharaoh/runs/<timestamp>/ containing:

• Summary: N passed / M failed / K skipped.
• Per failed test: file path, failure type, most-likely cause, suggested fix path.

Tell the user the run is stopped and point them at the diagnosis. The run directory retains TEST_PLAN.md, generated files, run.log, and the diagnosis — they can resume manually.

11. Completion

On clean run, print the summary, commit the generated tests on behalf of the user only if they explicitly ask, and stop.