메뉴
Write tests for the current Android branch driven by a user story + ACs, adhering to the project's existing conventions. Run inside an Android project's branch.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | test-scribe |
| description | Write tests for the current Android branch driven by a user story + ACs, adhering to the project's existing conventions. Run inside an Android project's branch. |
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-scribemust be invoked from the main session (it requires interactive review gates). Please exit this subagent and invoke/test-scribedirectly, 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.
You may NEVER open production .kt / .java files directly with Read, cat, head, view, or any equivalent tool. The only sanctioned mechanism for inspecting a production class's surface during this workflow is the bundled signature extractor (see Step 4):
<plugin-dir>/scripts/kotlin-signatures/bin/kotlin-signatures <path/to/Class.kt>
This rule applies at every step — Preflight, Discovery, Scope inference (Step 3), Gate 0 reasoning, plan synthesis (Step 6), Gate 1 narration, every clarification question, every status update.
Forbidden:
.kt / .java file directly to "understand what it does", to justify scope, to write a Gate 0 summary, or to enrich a clarification question.Y ?: Z", "method M sets field F from G", "this contains the canBeDeselected branch") — those are body-reads even when paraphrased. If you find yourself wanting to write that kind of sentence, STOP and run the extractor first; describe only what the extractor's output shows.Allowed:
find, ls, git ls-files, git diff).grep -l, grep -n for declaration sites only — pattern matching is allowed; opening the matched file's body is not).build.gradle.kts, settings.gradle.kts, libs.versions.toml, *.toml, *.properties)..claude/test-pharaoh/runs/<timestamp>/extracts/....src/test/**/*.kt, src/androidTest/**/*.kt) — those are not production bodies and are explicitly allowed for context.Sequencing implication: If you need to know more about a candidate class than its name and grep matches, run the extractor on it before saying anything substantive about it. Do not read the body first and run the extractor later as cover.
If the extractor fails on a class, mark that class as EXTRACTOR FAILED in the plan and skip it — do NOT fall back to reading the body.
Before starting the workflow, verify these prerequisites. If any fails, stop with a clear message — do NOT proceed into Step 1.
<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)
<plugin-dir>/scripts/kotlin-signatures/bin/kotlin-signatures is executable (test -x). If not, tell the user to chmod +x it.git rev-parse --is-inside-work-tree). If not, stop — /test-scribe only operates on a branch.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.
.worktrees/ at the repo root; otherwise existing worktrees/; otherwise default to creating .worktrees/.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.tests/<feature-slug> based on the story title; accept overrides.git worktree add <parent>/<dir-safe-name> -b <branch-name>. Replace / with - in the directory path only; keep the branch name as-is.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.
Generate a fresh ISO-8601 UTC timestamp for this run and create its directory before moving to Step 1:
TIMESTAMP=$(date -u +%Y%m%dT%H%M%SZ) # e.g. 20260426T142105Z
mkdir -p .claude/test-pharaoh/runs/$TIMESTAMP
Use $TIMESTAMP consistently throughout this workflow for every artefact:
.claude/test-pharaoh/runs/$TIMESTAMP/extracts/....claude/test-pharaoh/runs/$TIMESTAMP/TEST_PLAN.md.claude/test-pharaoh/runs/$TIMESTAMP/run.log.claude/test-pharaoh/runs/$TIMESTAMP/diagnosis.mdHard rules:
/test-scribe invocation. Never reuse an existing run directory.$TIMESTAMP is set..claude/test-pharaoh/runs/20260426T142105Z/"). This lets the user follow along and locate artefacts./test-scribe with these inline, use them; otherwise stop and prompt. Never continue with a blank or inferred spec..claude/test-pharaoh/config.json. If parentBranch is set, use it.develop, main, master (in that order). Use the first one that exists.config.json.git diff <parent>...HEAD (three-dot syntax — commits unique to this branch).gradle/libs.versions.toml (SHA-256). If .claude/test-pharaoh/project-profile.json exists AND its versionCatalogHash matches, reuse it.architect subagent with the repo root as input. It writes a fresh profile.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.Per the global source-reading discipline above, you may not read production .kt bodies during scope inference. Use only file paths, module structure, and grep/find pattern matching by symbol name. If a candidate class needs deeper inspection to justify inclusion, run the extractor on it (Step 4 procedure) and use the extract — do NOT open the source file.
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. Identify candidates via git diff --name-only plus AC-concept grep; do not open the changed files.grep -l/find. For each shortlisted candidate, run the extractor (per Step 4) BEFORE writing scope justifications — your justification text must be derivable from the extract alone, not from the file body. 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."When presenting the scope to the user, justify each candidate in terms the extractor's output supports — public function signatures, return types, parameter lists, class-level KDoc that the extractor exposes. Do NOT paraphrase what a function's body does ("maps X ?: Y", "sets selectByDate from chooseByDate"). If a justification requires body-level detail, that's a signal to either (a) restate the justification at signature level, or (b) drop the candidate and let the user surface it if they want it in scope.
<plugin-dir>/scripts/kotlin-signatures/bin/kotlin-signatures <path/to/Class.kt>
.claude/test-pharaoh/runs/<timestamp>/extracts/<mirror-path>/<Class>.kt.EXTRACTOR FAILED — write tests for <Class> manually. Do NOT fall back to reading the body.Open with a short inline summary (3–5 bullets) as an anchor:
## Out of scope annotation in Step 6.Then, instead of a single "does this look right?" question, interview the user one question at a time until the feature is unambiguous. Walk the feature's decision branches in dependency order — scope, undo/revert behaviour, error and empty/null paths, idempotence, concurrency, per-tier coverage — resolving each before moving to the next. Treat scope as a quick first pass, then spend the interview on the AC-gap edges — the behaviours the ACs leave unstated (undo/revert, concurrency, empty/null, error and failure paths). Those edges are where test-relevant misunderstandings hide; don't let scope-setting or restating the ACs consume the interview before you reach them. For every question, propose your recommended answer ("I'd assume X because AC-2 says Y — correct?") so the user confirms or corrects rather than starting from a blank page. Ask, wait for the reply, then ask the next. A foundational misunderstanding caught here is cheap; at later gates it costs plan synthesis or generated tests.
Self-answer what you can — from the right sources only. If a question is answerable from project-profile.json, module structure, git diff, grep-by-name, or an existing signature extract, answer it yourself instead of asking the user. Never read a production .kt/.java body to self-answer — the source-reading discipline above holds at this gate too. (This is the one place the technique departs from a generic grilling skill: "explore the codebase to answer it" means the extractor and existing tests here, never the production body.)
Surface contradictions against the observable surface. If the user's AC narrative conflicts with what a signature extract or an existing test file shows, raise it verbatim — "the extract for X exposes only Y; you said Z is possible — which is right?" Check the user's claims against the extract and existing tests, never against production bodies.
Loop until the user confirms. Only then proceed.
For every AC, extract:
Build the matrix (parameters × verbs). Every cell needs a planned test. If a cell is genuinely redundant (code-path-identical to a sibling), do not omit it silently — record it in the plan as an explicit skipped-cell note with a one-line justification, e.g.:
- [~] user_UNLOADED_newApp_canSelect — skipped: same code path as user_UNLOADED_oldApp_canSelect (gate relies on 'isSelected()' branch, not the flag)
The user reviews this at Gate 1. They, not the synthesizer, decide whether shared code paths justify fewer tests. Default to symmetric coverage when in doubt.
Apply these rules when naming every test you list in the plan. Test names are set here, not by mason — so get them right at synthesis time.
Match the project's existing test-naming convention. Before naming anything, read 2–3 existing test files in the target module. Common styles include backticked prose, snake_case, and camelCase. The architect's project-profile.json may record conventions.testNamingStyle; when present, use it — but still spot-check against existing tests in the target module, since conventions can vary between modules. Never invent a style that doesn't match the module.
No drift-prone parentheticals. A parenthetical that reads like one action sitting next to a test body asserting a different action is broken. Never let a parenthetical disagree with what the test asserts.
Echo AC language literally — verbs and conditions, from the AC that asserts the behavior under test. Copy the AC's wording verbatim for both the action verb and any condition attached to it. Do not paraphrase, generalize, or substitute phrasing from a sibling AC about UI text or labels. When multiple ACs use different phrasings, pick the AC that asserts the behavior, not a sibling AC about UI text. Naming drift breaks traceability.
Prefer the pattern <subject> can be <AC-verb>ed <condition> when the AC is phrased as a capability. Other sentence shapes are fine as long as rule 3 holds. If the project convention forbids prose (e.g. strict snake_case), adapt the pattern to that style while keeping the AC verbs + conditions as tokens.
One test per matrix cell — no compression. Do not collapse multiple matrix cells into one name. One test = one matrix cell; compression breaks traceability.
Regression guards describe the guarded branch, not a forced capability phrase. If the branch being guarded is an error, disabled, or invariant state, the test name asserts that state directly. Rule 4's pattern is for AC-driven capability tests; regression guards describe contract invariants and may need a different shape.
Before listing tests, decide which tiers apply for each class in scope. Default tier selection:
project-profile.json → instrumentedTier.tierName — e.g. "cucumber", "espresso", "compose-ui"): treat as a decision point whenever the user story or any AC contains user-facing interaction signals. You may propose to include or to omit, but you must surface the decision explicitly at Gate 1 as a clarification question — never make it silently. If instrumentedTier.present = false (project has no instrumented-test setup at all), surface that at Gate 1 too — interaction-driven ACs may not be testable end-to-end without introducing that setup, which is a scoping decision the user owns.User-facing interaction signals — if any of the following appear in the story or ACs, you must explicitly ask the user about the instrumented tier at Gate 1:
Rationale: unit tests verify pure data transformation. An AC phrased as a user capability (e.g. "Member can select voucher on expiry date") is an end-to-end behavioural claim — the underlying mapping passing does not prove the user can perform the action in the running app. Only the instrumented tier closes that gap. But whether to spend the time on instrumented scenarios is a project-specific judgement call the user owns.
The Gate 1 clarification question is mandatory when interaction signals are present. Phrase it along the lines of:
The ACs include user-interaction signals: [list the specific signals you detected, quoted from the story/ACs]. I have [included / omitted] the instrumented tier in this plan because [one-line rationale]. Do you want me to [add / keep / remove] instrumented-tier coverage? If so, I propose the following scenarios: [list].
Never drop the instrumented tier without posing this question. The user decides.
Write the plan to .claude/test-pharaoh/runs/$TIMESTAMP/TEST_PLAN.md. The file is mandatory — presenting the plan inline in chat only is a workflow violation; the file must exist on disk before you reach Gate 1. Use the timestamp generated in the "Initialize run directory" step.
For each class in scope and each applicable tier (unit, integration, roborazzi, cucumber), list the planned tests with traceability markers in the file. Example format (the naming style shown here is one of several valid styles — use whatever matches the target module per the "Naming the tests" rules above):
### 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:
## Out of scope section listing behaviours/subsystems adjacent to the diff, or named near the ACs, that this plan deliberately does NOT cover — one line each with a reason (e.g. - analytics events — not in the diff; covered by a separate suite). Derive these from class/subsystem names only (git diff --name-only + AC-concept grep), never from class bodies. It stops over-testing adjacent code the diff and ACs don't ask for, and gives the user an explicit boundary to challenge at Gate 1.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.This gate has two distinct stages. Do not conflate them. Approval of the plan's shape is not authorization to generate code. You must obtain both, in sequence, before any mason is dispatched.
Tell the user the plan has been written and give them the path: .claude/test-pharaoh/runs/<timestamp>/TEST_PLAN.md. They review the file, edit it directly, or answer any clarification questions the plan raised. Iterate here as long as needed — plan correctness is cheaper to fix than generated tests.
Do NOT interpret generic approval ("looks good", "that's fine", "great", "sounds right", "nice") as authorization to implement. Those phrases confirm the plan is readable; they do not unlock generation. Implementation authorization is a separate, explicit step — see 7b.
Once the user has finished reviewing the plan AND every clarification question from 7a has been resolved, you must pose Gate 1b as its own standalone prompt — not bundled with any other question, not implied, not combined with a clarification response. Exact wording doesn't matter, but it must be unmistakably a new, single-purpose question:
The plan is finalized. Ready for me to generate these N tests? Reply "go" / "implement" / "proceed" to start. Anything else — including further plan edits — I'll treat as non-authorization.
Hard rules:
Gate 1b stands alone. Do NOT fold it into the same turn where you resolve a Cucumber / clarification / refactor question. Close those first. When every clarification is resolved, pose 7b by itself.
Only a direct response to the Gate 1b prompt counts as authorization. Answers to earlier questions — no matter how affirmative they sound (e.g. "yes add the Cucumber tests", "that's fine, proceed with the plan") — are NOT the go-signal. They're responses to those earlier questions, even if the user's prose sounds like consent. Re-ask 7b explicitly after any such response.
Valid go-signals (only when given in direct response to the 7b prompt): go, implement, proceed, yes, generate, write the tests, or any equally unambiguous directive to start generating code.
Invalid — treat as non-authorization and re-pose 7b:
Re-authorize on plan change. If the plan is edited after a go-signal, the authorization expires. Pose 7b again before dispatching.
Under no circumstances may you dispatch a mason without a go-signal that was given in direct response to a standalone 7b prompt.
Precondition: 7b has been completed and the user has given an explicit go-signal. If 7b has not been completed or the signal was ambiguous, return to 7b — do not proceed.
For each (class × tier) in the authorized plan, 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.
Run the complete module task for every tier touched by the generated tests — no --tests filter, no single-class shortcut. The physician can only triage what it sees in run.log; partial coverage of the generated changes is a workflow failure, not a time-saver.
For every module that received new or modified test files in Step 8, enumerate one Gradle task per tier in the plan:
:loyalty:testQaUnitTest). Runs the whole test source set.:verifyRoborazziDebug or profile-specified equivalent. Full run.profile.instrumentedTier.tierName) → :connectedXxxAndroidTest if a device is available (see 9c); regardless of device availability, also run the instrumented-source compile task (e.g. :loyalty:compileQaAndroidTestKotlin) so compilation errors in the generated feature files / step definitions / dispatcher changes are caught.Prohibited:
--tests "<fully-qualified.ClassName>" or any filter that narrows below the module task. Always run the full module task.Invoke each task (sequentially or in parallel where independent). Every invocation must have its stdout + stderr appended to .claude/test-pharaoh/runs/<timestamp>/run.log. If you cannot write to run.log, stop and escalate — running tests without persisting output is itself a workflow violation.
Apply a per-Gradle-task timeout (default 5 minutes). If a task hangs past the timeout, kill it, append a TIMEOUT <task> line to run.log, and escalate directly to Gate 2 — do not retry hung tasks.
Before invoking connectedXxxAndroidTest, run adb devices and append its output to run.log. If no device/emulator is connected:
run.log with a line like SKIPPED :loyalty:connectedQaAndroidTest — no device (compile-only verified).If any task produced failures (compilation errors, test failures, setup errors), dispatch physician with run.log and the full list of generated test files.
Before marking Step 9 complete, verify run.log contains a result row (pass, fail, skipped-with-reason, or not-executed-with-reason) for every test listed in TEST_PLAN.md. If any planned test has no corresponding row, the run is incomplete — return to 9a, extend the task set, and re-run. Missing coverage may not be swept under the rug; it must be either executed or explicitly recorded in run.log with a reason before you advance to Step 11.
Write diagnosis.md under .claude/test-pharaoh/runs/<timestamp>/ containing:
N passed / M failed / K skipped.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.
On a clean run — every planned test executed and green — perform one static audit of the written test files before declaring done. This is not a new interactive gate and it re-runs nothing: it re-reads the generated test files (read-allowed) and checks them against two independent sources, reporting findings as two separately-headed lists. Do NOT merge or rerank the two lists — a convention pass must not mask a coverage gap, and vice versa. The source-reading discipline still applies: never open a production .kt/.java body during the audit. Cite the profile field or the AC for each finding.
project-profile.json. Flag divergences in fixture placement, assertion library, dispatcher pattern, error-wrapper usage, runner wiring, and test-naming style — plus any mock that slipped in despite the never-mocks rule. Cite the violated profile field per finding.TEST_PLAN.md matrix cell vs the emitted tests. Flag cells with no corresponding test that weren't recorded as an explicit skipped-cell, tests whose assertions don't actually exercise the AC they're mapped to, and source: markers with no matching test. Quote the AC per finding.Surface both lists to the user as part of the completion summary. The user rules on whether to fix, accept, or ignore each finding — you do not silently edit passing tests. If asked to fix Standards findings, treat convention violations like mechanical patches (apply, then re-run the full module task per Step 9); if asked to fill a missing Spec cell, return to Step 8 (dispatch a mason for that cell), then Step 9. If the audit finds nothing on either axis, say so in one line and proceed.
On clean run, print the summary (including the 11a audit result), commit the generated tests on behalf of the user only if they explicitly ask, and stop.