Imported from gmcoolsr/VpnFakeService (.cursor/skills/test-plan-human/SKILL.md). Install upstream with npx skills add gmcoolsr/VpnFakeService --skill test-plan-human. Copyright stays with the author.

Human Test Plan

Token discipline: apply ../../_shared/token-discipline.md and its project overlay at every step; it never outranks evidence, gate, test, or stage rules.

Create one auditable Excel plan that covers the changed functionality and every material area the change can break. Orchestrate analysis only; do not change product code, write automated tests, run product test suites, or let subagents edit the workbook unless the user separately requests those actions.

Inputs and defaults

Collect:

repository root;
base_ref and head_ref;
optional issue/acceptance context;
diff mode: merge-base by default, or explicit tip-to-tip, commit-range, or WORKTREE;
optional output path.

If refs are omitted, infer them from the request and repository state when safe. Ask only when different choices would materially change scope. Exclude uncommitted and untracked files unless the user explicitly selects WORKTREE.

Use assets/Sferio_Regression_Test_Plan.xlsx as the immutable visual reference and assets/preview.png as its representative first-sheet preview. The asset keeps the etalon's filename because that is the file on disk; it is a layout reference only, and nothing in it is a fact about this product. Always create a new workbook; never overwrite the asset or an existing output.

Mandatory repository reads

From the target repository checkout, read AGENTS.md, then the current versions of:

docs/agents/source/skills/impact-graph/SKILL.md;
docs/agents/adapter-config.yml (graphTooling, verification);
docs/tooling/impact-graph-runbook.md;
docs/agents/source/_shared/project/backend-participation-evidence.md;
docs/agents/source/_shared/project/external-graph-evidence.md;
docs/agents/source/_shared/regression-risk-traceability.md;
docs/testing/runbook.md and the catalogs for affected surfaces.

Treat repository rules as current source of truth. Do not copy older graph claims from tickets, plans, comments, memory, or workbook rows.

1. Freeze the diff snapshot

Do not checkout, reset, clean, rebase, merge, or alter the user's worktree.

Resolve refs with git rev-parse --verify <ref>^{commit}.
Record base SHA, head SHA, merge-base SHA, current branch, dirty state, diff mode, and inclusion policy.
For default branch comparison, analyze git diff --find-renames --find-copies <base>...<head> and collect --name-status, --stat, --numstat, relevant hunks, and git log <base>..<head>.
For tip-to-tip or a literal commit range, record that semantic explicitly.
For WORKTREE, inventory committed range, staged, unstaged, and untracked inputs separately. Do not silently fold them into one diff.
Detect shallow history, invalid refs, submodules, binaries, generated files, renames, and missing merge-base. Record gaps instead of guessing.
Re-resolve the snapshot before export. Stop or refresh evidence if refs or included worktree state changed.

Assign every production change a stable CHG-#. Classify product, layer, behavior/contract, symbol/route/table/config key, and new, changed, removed, or non-behavioral with rationale.

2. Launch read-only subagents

Use subagents for every non-trivial diff. Read references/subagent-packets.md and launch the smallest complete set, normally in parallel:

diff and behavior mapper — always;
backend impact analyst — when control-api/ participates or remains unknown;
frontend flow analyst — when portal/ or a frontend contract participates;
network-core analyst — when core/, gateway/, or apps/** participates; these surfaces have no impact graph, so the lane works from targeted rg, source reads and docs, and every claim it returns is labelled fallback;
cross-cutting risk analyst — always for C2/C3 or integration, data, auth, session-ticket, capacity-reservation, revocation, background-job, migration, config, or concurrency changes;
independent coverage reviewer — only after a draft matrix exists.

Give every subagent exact SHAs/worktree policy, owned areas, mandatory reads, Do not change boundaries, allowed read-only checks, expected schema, and done criteria. Subagents return evidence slices only. They must not edit the workbook or product files. Do not duplicate their active work; wait for explicit results before synthesis.

3. Determine blast radius

Classify backend participation as yes, no, or unknown.

The impact graph covers control-api/ and portal/ only. core/, gateway/, apps/windows, apps/apple, apps/android, infra/ and tests/network/ have no graph builder at all: for those, blast radius is fallback evidence, never graph-backed. docs/agents/adapter-config.yml currently sets graphTooling.enabled: false because no code exists yet, so today every graph status is unavailable — record it as such rather than omitting the row.

For control-api/:

Use targeted rg for routes, strings, config, permissions, migrations, schemas, tests, docs, and candidate C# symbols.
Query a fresh graph through impact-graph-analyst or a current-run docs/tooling/impact-graph/graphctl.py query only.
Run callers, sites, and blast --depth 2 for material changed symbols. Extend to depth 3 for shared contracts, authentication, session-ticket issue and validation, capacity reservation, device revocation, state machines, or when depth 2 does not reach a stable API/job/user boundary.
For renamed or removed symbols, analyze the base snapshot in a separate read-only worktree or explicitly mark base-graph evidence unavailable; then verify remaining references on head.
Reject stale or ambiguous graph results. Record missing, stale, ambiguous, or unavailable precisely and continue with labelled fallback evidence without claiming graph-backed blast radius.

For portal, run the same three tasks with --project portal; the graph resolves components, pipes, class fields, and their template binding sites. Still inspect styles, routing intent, guards, RxJS flows, and UX docs manually — the graph does not cover them. Never present a query against one project's graph as evidence about another.

Convert every material changed, direct, transitive, string/config/schema, integration, and manual UI impact into stable IMP-# evidence with affected surface, relation, distance, failure mode, roles/states/environments, source, freshness, and limits.

4. Build risks and human cases

Create stable RR-# rows for plausible regression paths. Include affected functionality, concrete coupling, detection evidence, mitigation/owner, and status.

Generate cases for every applicable category:

new behavior: happy path, validation/negative, boundary, and permissions;
direct and transitive regressions;
state transitions, forbidden transitions, retry, cancellation, race, and idempotency;
producer/consumer contract and backward compatibility;
migrations, backfill, data integrity, indexes, rollback or safe-forward handling;
integrations: timeout, retry, duplicate, signature, status mapping, and partial failure;
authentication, authorization, role/tenant isolation, input handling, and PII/secret redaction;
missing/invalid/default config, restart, DI lifecycle, jobs, and scheduling;
capacity, device-limit, and lease mutation: duplicate reservation, concurrent admission for the same account, partial write, recovery after a control-channel loss, and reconciliation of reservations against live leases;
tunnel-behavior cases when core/, gateway/, or apps/** participates: routing-rule evaluation order (system, master switch, user rules, default profile, fallthrough), split-tunnel DNS resolver selection, kill-switch behavior in split mode, MTU and Packet Too Big handling on both IP families, client isolation, and device revocation taking effect inside the lease window. These are executed against the tests/network/ lab, not a browser;
frontend loading, empty, error, unauthorized, refresh, deep-link, back-navigation, responsive, theme, and accessibility states when applicable.

Write tests a human can execute. Each case must have a unique ID, exact actor, preconditions, concrete data, numbered actions, one observable expected result per step, cleanup/postcondition, environment, priority, case type, and mappings to CHG, IMP, RR, and evidence IDs. Reject vague cases such as “check everything works.”

Deduplicate only when surface, actor, initial state, action, expected invariant, failure mode, and environment/provider are equivalent. Preserve separate cases for different roles, transitions, concurrency timing, providers, schema versions, or recovery modes.

5. Close coverage

Read references/evidence-contract.md and references/workbook-contract.md, then create one normalized JSON input.

Require:

every production CHG-# classified;
every material CHG-#, IMP-#, and RR-# mapped to at least one test or an explicit EXC-# with reason, evidence, owner, and follow-up;
every direct graph consumer accounted for;
transitive impact followed to an observable boundary or recorded limit;
no orphan P0/P1 impact, no orphan test case, no duplicate ID;
cross-layer contracts tested from both producer and consumer sides and through a human journey when applicable;
every backend graph claim tied to current-run provenance;
unknowns and blocked environments visible as coverage gaps, never silently omitted.

Ask the independent coverage reviewer to audit the draft matrix. Incorporate only evidence-backed additions and preserve traceability IDs.

6. Generate and verify Excel

Use the bundled Spreadsheets runtime and @oai/artifact-tool only.

Call the workspace dependency loader.
Create a temporary working directory and link its node_modules to the loader-provided package directory.
Copy scripts/build_test_plan.mjs into that directory so ESM resolves the linked dependencies.
Run the copied script with absolute --input, --template, and --output paths. The input must conform to references/evidence-contract.md.
Inspect required ranges, scan for formula errors, and render every visible non-empty sheet.
Visually verify headers, filters, freeze panes, wrapping, row heights, long steps, colors, and absence of clipped content.
Verify IDs and traceability from workbook readback. Do not pass with missing required fields or unmapped material risks.

Use a unique default name such as VpnFakeService_Test_Plan_<base>_to_<head>_<timestamp>.xlsx under outputs/<thread-id>/.

Output

Return the absolute workbook path and a concise summary containing exact refs/SHAs, diff mode, changed-file count, new/regression case counts, graph status per affected project, coverage counts, explicit gaps/blockers, and completed subagent lanes.

Do not claim the plan proves the absence of unknown runtime dependencies. State graph and environment blind spots in the workbook and summary.

test-plan-human

About