/manual-test-planning

name: manual-test-planning
description: >
  Produce a plain-language manual test plan from the context supplied to it — an executive summary, a high-level list
  of named tests, and a detail section per test with the steps a person follows by hand and the outcomes they should
  expect. Use when you want to create, draft, generate, or outline a manual test plan, manual QA steps, hands-on
  verification steps, or an acceptance walkthrough for a feature, change, branch, plan, or PR. When the plan holds
  more than five tests and at least two natural categories emerge, both the test list and the detail sections are
  organized under plain-language categories. When nothing in the
  supplied context can be manually tested, it says so and asks for more context instead of producing a document. Does
  not analyze code for automated test coverage gaps — use automated-test-planning. Does not write test code — use tdd. Does not
  review code quality — use code-review. Does not stress-test an existing plan — use iterative-plan-review.
argument-hint: "[optional: files, a branch, a plan, a PR, or a description of what to manually test]"
allowed-tools: Bash(git *), Read, Grep, Glob, Write, Agent, Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Operating Principles

• **Group outcomes only when the steps are identical.** A test verifies a single outcome, or a group of related

outcomes only when the exact same steps produce every outcome in the group. If any outcome needs a different or additional step, it gets its own test, BECAUSE a person following one step list can only check the outcomes those steps actually produce.

• **Every test states its expected outcomes.** A step list without an expected outcome is not a test. Each test's

detail section ends with the outcome or outcomes the person should observe, so they can tell pass from fail on the spot.

• **No manual tests means no document.** When the supplied context contains nothing a person can test by hand, say so

clearly and ask for more context instead of writing a file. Never invent or pad testable outcomes, BECAUSE a plan built on guesses sends the tester chasing outcomes the work never promised.

• **Plain language only.** The plan is written for the person who runs the tests by hand, who may not be technical.

Short, concise sentences. No file paths, function names, code, or framework jargon anywhere in the document. Describe what the person does and sees through the product's own surfaces (screens, commands, pages, messages), not how the code works, BECAUSE the reader follows the plan without ever reading the code.

Step 1: Gather the Context

Collect everything supplied to the skill call: the arguments, the conversation so far, and any files, plans, specs, diffs, or pull requests referenced. Read referenced files with Read. If a branch, PR, or change set is referenced and git is available, use `git diff`, `git log`, and `git status` to understand what changed; if git is unavailable or the directory is not a repository, skip the git commands and work from the rest of the supplied context. The git detail informs your understanding only — none of it appears in the plan.

If no context was supplied at all, ask the user what they want a manual test plan for, and wait for their answer before continuing.

Step 2: Identify What Can Be Manually Tested

From the context, list every candidate outcome a person can verify by hand. An outcome qualifies only when all three hold:

1. A person can reach it through the product's own surfaces: a screen, a page, a command they can run, a request they can send, a document or message they can read. 2. The steps to reach it can be written without asking the person to read or change code. 3. The result is something the person can directly observe and compare against an expectation.

Internal refactors, dependency bumps, code style changes, and behavior only observable in test suites or logs the person cannot see do not qualify.

**If the list is empty:** tell the user clearly that nothing in the provided context can be manually tested, and ask whether there is additional context to consider. If they supply more, return to Step 1 with the combined context. If they say there is none, end the skill with that statement as its only output — do not write a file and do not produce a document.

Step 3: Group Outcomes into Named Tests

Turn the outcomes into a list of named tests:

1. Default to one test per outcome. 2. Merge outcomes into one test only when the exact same steps produce every outcome in the group. When in doubt, keep them separate. 3. Give each test a short, unique, plain-language name that says what it verifies (for example, "Signing in with a wrong password"), not how. 4. Order the tests in the sequence a person would sensibly run them: tests that set up state other tests rely on come first, then the most important behaviors, then the rest. 5. Count the tests. When there are more than 5, look for natural plain-language categories among them — by the area of the product they exercise, the kind of person who runs them, or the feature they verify. When at least two natural categories emerge, categorize: assign each test to exactly one category, name each category with the same sho