{"slug":"manual-test-planning","title":"manual-test-planning","summary":"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, gener","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-15T13:11:59.008077Z","repo":{"url":"https://github.com/testdouble/han","stars":303,"forks":24,"license":"MIT","updatedAt":"2026-10-14T20:22:28Z"},"bodyHtml":"<hr>\n<h2>name: manual-test-planning\ndescription: &gt;\nProduce a plain-language manual test plan from the context supplied to it — an executive summary, a high-level list\nof named tests, and a detail section per test with the steps a person follows by hand and the outcomes they should\nexpect. Use when you want to create, draft, generate, or outline a manual test plan, manual QA steps, hands-on\nverification steps, or an acceptance walkthrough for a feature, change, branch, plan, or PR. When the plan holds\nmore than five tests and at least two natural categories emerge, both the test list and the detail sections are\norganized under plain-language categories. When nothing in the\nsupplied context can be manually tested, it says so and asks for more context instead of producing a document. Does\nnot analyze code for automated test coverage gaps — use automated-test-planning. Does not write test code — use tdd. Does not\nreview code quality — use code-review. Does not stress-test an existing plan — use iterative-plan-review.\nargument-hint: \"[optional: files, a branch, a plan, a PR, or a description of what to manually test]\"\nallowed-tools: Bash(git *), Read, Grep, Glob, Write, Agent, Bash(bash \"$/scripts/han-config-dir.sh\")</h2>\n<h2>Project Context</h2>\n<ul>\n<li>personal config directory: !<code>bash \"${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh\" 2&gt;/dev/null || echo \"$HOME/.claude\"</code></li>\n<li>project .han/config.md: !<code>cat .han/config.md 2&gt;/dev/null || echo \"\"</code></li>\n</ul>\n<p>As your first action, use the Read tool on <code>.han/config.md</code> inside the <code>personal config directory</code> path above. A read\nthat returns no file is no personal configuration: continue silently. When that file or the <code>project .han/config.md</code>\nprobe supplies content, apply it per <a href=\"../../references/config-rule.md\">config-rule.md</a>, which governs precedence\nbetween the two files, relative-path resolution, and what to do with a file that reads but cannot be used.</p>\n<h2>Operating Principles</h2>\n<ul>\n<li><strong>Group outcomes only when the steps are identical.</strong> A test verifies a single outcome, or a group of related\noutcomes only when the exact same steps produce every outcome in the group. If any outcome needs a different or\nadditional step, it gets its own test, BECAUSE a person following one step list can only check the outcomes those\nsteps actually produce.</li>\n<li><strong>Every test states its expected outcomes.</strong> A step list without an expected outcome is not a test. Each test's\ndetail section ends with the outcome or outcomes the person should observe, so they can tell pass from fail on the\nspot.</li>\n<li><strong>No manual tests means no document.</strong> When the supplied context contains nothing a person can test by hand, say so\nclearly and ask for more context instead of writing a file. Never invent or pad testable outcomes, BECAUSE a plan\nbuilt on guesses sends the tester chasing outcomes the work never promised.</li>\n<li><strong>Plain language only.</strong> The plan is written for the person who runs the tests by hand, who may not be technical.\nShort, concise sentences. No file paths, function names, code, or framework jargon anywhere in the document.\nDescribe what the person does and sees through the product's own surfaces (screens, commands, pages, messages), not\nhow the code works, BECAUSE the reader follows the plan without ever reading the code.</li>\n</ul>\n<h2>Step 1: Gather the Context</h2>\n<p>Collect everything supplied to the skill call: the arguments, the conversation so far, and any files, plans, specs,\ndiffs, or pull requests referenced. Read referenced files with Read. If a branch, PR, or change set is referenced and\ngit is available, use <code>git diff</code>, <code>git log</code>, and <code>git status</code> to understand what changed; if git is unavailable or the\ndirectory is not a repository, skip the git commands and work from the rest of the supplied context. The git detail\ninforms your understanding only — none of it appears in the plan.</p>\n<p>If no context was supplied at all, ask the user what they want a manual test plan for, and wait for their answer\nbefore continuing.</p>\n<h2>Step 2: Identify What Can Be Manually Tested</h2>\n<p>From the context, list every candidate outcome a person can verify by hand. An outcome qualifies only when all three\nhold:</p>\n<ol>\n<li>A person can reach it through the product's own surfaces: a screen, a page, a command they can run, a request they\ncan send, a document or message they can read.</li>\n<li>The steps to reach it can be written without asking the person to read or change code.</li>\n<li>The result is something the person can directly observe and compare against an expectation.</li>\n</ol>\n<p>Internal refactors, dependency bumps, code style changes, and behavior only observable in test suites or logs the\nperson cannot see do not qualify.</p>\n<p><strong>If the list is empty:</strong> tell the user clearly that nothing in the provided context can be manually tested, and ask\nwhether there is additional context to consider. If they supply more, return to Step 1 with the combined context. If\nthey say there is none, end the skill with that statement as its only output — do not write a file and do not produce\na document.</p>\n<h2>Step 3: Group Outcomes into Named Tests</h2>\n<p>Turn the outcomes into a list of named tests:</p>\n<ol>\n<li>Default to one test per outcome.</li>\n<li>Merge outcomes into one test only when the exact same steps produce every outcome in the group. When in doubt,\nkeep them separate.</li>\n<li>Give each test a short, unique, plain-language name that says what it verifies (for example, \"Signing in with a\nwrong password\"), not how.</li>\n<li>Order the tests in the sequence a person would sensibly run them: tests that set up state other tests rely on come\nfirst, then the most important behaviors, then the rest.</li>\n<li>Count the tests. When there are more than 5, look for natural plain-language categories among them — by the area\nof the product they exercise, the kind of person who runs them, or the feature they verify. When at least two\nnatural categories emerge, categorize: assign each test to exactly one category, name each category with the same\nshort plain-language rule as test names, and put every test that fits no natural category under a final category\nnamed \"Other tests\". Keep the run order: categories in the order their first test would run, \"Other tests\" last,\nand tests in run order within each category. When only one natural category emerges, or none do, keep the flat\nlist, BECAUSE a single category or a forced grouping adds structure without helping the tester see how the tests\nrelate. With 5 tests or fewer, always keep the flat list.</li>\n</ol>\n<h2>Step 4: Draft the Plan</h2>\n<p>Invoke <code>han-communication:readability-guidance</code> to source the shared readability standard into your context, then\ndraft the document using the template at <a href=\"./references/template.md\">references/template.md</a>:</p>\n<ul>\n<li><strong>Summary</strong> — the executive summary: 2-4 short sentences on what the plan covers, who can run it, how many tests it\ncontains, and where to start.</li>\n<li><strong>Tests at a Glance</strong> — the high-level list: every test name with one sentence on what it verifies.</li>\n<li><strong>Test Details</strong> — one section per named test: one sentence on what it verifies, a numbered list of steps to follow,\nand the expected outcome or outcomes.</li>\n</ul>\n<p>When Step 3 produced categories, organize both Tests at a Glance and Test Details under the category names, following\nthe categorized layout in the template: each category is a heading in both sections, its tests sit beneath it, and the\ncategories and tests appear in the same order in both sections, BECAUSE the reader jumps between the glance list and\nthe details by matching names.</p>\n<p>Apply the Operating Principles as you write: short sentences, plain words, no technical detail, expected outcomes in\nevery detail section.</p>\n<h2>Step 5: Adversarially Validate the Plan</h2>\n<p>Dispatch the <code>han-core:adversarial-validator</code> agent (one Agent call) against the draft before writing any file,\nBECAUSE a plan that reaches the tester with wrong steps or unpromised outcomes wastes their run and hides real\nfailures. Embed the full draft in the agent's prompt, along with the scope of the context it was derived from (the\nfile paths, branch, plan, or description from Step 1), and instruct it to try to disprove, for every test:</p>\n<ol>\n<li>The expected outcomes are actually promised by the supplied context, not invented or assumed.</li>\n<li>The steps, followed exactly as written, reach and produce every stated expected outcome.</li>\n<li>A person can perform every step through the product's own surfaces without reading or changing code.</li>\n<li>Grouped outcomes are truly produced by the exact same steps, with no outcome needing a different or additional\nstep.</li>\n</ol>\n<p>Apply every confirmed finding to the draft:</p>\n<ul>\n<li>Fix steps that would not produce their stated outcome.</li>\n<li>Correct or remove expected outcomes the context does not promise.</li>\n<li>Split a grouped test when any of its outcomes needs different steps.</li>\n<li>Remove a test entirely when its outcome cannot be validated against the context.</li>\n</ul>\n<p>If every test is removed, return to the empty-list handling in Step 2: state that nothing in the context can be\nmanually tested and ask for more context. If a finding turns on ambiguity in the context rather than an error in the\ndraft, surface it to the user with a recommended resolution instead of silently choosing.</p>\n<h2>Step 6: Write the File</h2>\n<p>Write the document to <code>manual-test-plan.md</code> in the current working directory, unless the user supplied a different\npath — the user's path wins.</p>\n<p>If <code>manual-test-plan.md</code> already exists, do not overwrite it. Pick a new unique filename derived from the current\ncontext: prefix the default name with one or two short plain-language words naming what the plan covers (for example,\n<code>sign-in-manual-test-plan.md</code> or <code>checkout-manual-test-plan.md</code>). Keep the name short, and always include\n<code>manual-test-plan</code> in it, BECAUSE the tester finds these documents by that name. Check the new name with Glob before\nwriting; if it also exists, adjust the prefix (or append a number) until the name is unique.</p>\n<p>If the user supplied a path and that file already exists, show the user the path and ask before overwriting, BECAUSE\noverwriting discards a document you did not produce in this run.</p>\n<h2>Step 7: Readability Edit and Self-Check</h2>\n<p>Dispatch <code>han-communication:readability-editor</code> (one Agent call) to audit and rewrite the plan's prose against the\nreadability standard. Pass it the file path and the named audience: the person who will run these tests by hand, who\nmay not be technical. The editor reads han-communication's own canonical rule, so pass no rule path. It must preserve\nevery fact — every step, expected outcome, test name, and category name must survive with its meaning intact.</p>\n<p>Then run the standardized readability self-check (the shared standard is in your context from\n<code>han-communication:readability-guidance</code>) over the document. Confirm each criterion and fix any failure:</p>\n<p>Run the readability rule's standardized self-check, which is already in your context from the <code>readability-guidance</code>\ninvocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs\nhow the content is said, and drops a required fact only when the reader asked for less and losing it would not change\nwhat they do next.</p>\n<p>Two checks are this skill's own, layered on top:</p>\n<ul>\n<li>Every test still has its steps and expected outcomes, and no technical detail has crept in.</li>\n<li>When the plan uses categories, Tests at a Glance and Test Details carry the same category names in the same\norder, with every test under its category in both sections.</li>\n</ul>\n<p>Finish by presenting a short in-channel summary: the file path, the number of tests, and the test names. Do not\nrepeat the full document in the channel.</p>\n","files":[{"path":"references/template.md","sizeBytes":2459,"isText":true},{"path":"SKILL.md","sizeBytes":11723,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-15T13:12:35.462268Z","sha256":"4B64E2D03757A8CEDD60FD6B489C7C7B919335E1AF89A9AE4137C409A08BEF02","sizeBytes":5754},"review":null,"source":{"repositoryUrl":"https://github.com/testdouble/han","path":"han-coding/skills/manual-test-planning","license":"MIT","commit":"abba73a773528905a8f3d15956029394746e5c7f","subtreeSha":"A5EDC1B66BA210E26672BF51CA5BC399794D6DF4A4A16146B135F0A09C71B87F","lastSyncedAt":"2026-10-15T13:11:53.672149Z"},"reviewedAt":"2026-10-15T13:14:00.899668Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/testdouble/han/tree/main/han-coding/skills/manual-test-planning"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install testdouble-han@llmmart"},{"target":"git","command":"git clone https://github.com/testdouble/han.git"}]}