# PunchList QA Plan — Skill

Use this skill when the user asks you to generate a QA plan, test plan, or test checklist intended for import into **PunchList**, a native Mac app for tracking QA passes. PunchList imports plans as a single `.md` file with a strict, parseable structure — deviating from the format means the import will fail or parse incorrectly.

---

## When to use this skill

Trigger this whenever someone asks for:
- "a QA plan for my app"
- "a test plan I can import into PunchList"
- "a punch list for [app/feature]"
- Any request to generate a structured test checklist for a Mac, iOS, or web app before a release

## Required output format

A single `.md` file, structured exactly as follows:

```markdown
# {App Name} v{Version} — QA Plan
*{One-line scope note}*

---

**Before starting QA:**
- [ ] {Pre-flight item}
- [ ] {Pre-flight item}

---

## SECTION 1 — {SECTION NAME, ALL CAPS}

| # | Test | Expected | Result | Notes |
|---|------|----------|--------|-------|
| 1.1 | {Action to take} | {What should happen} | | |
| 1.2 | {Action to take} | {What should happen} | | |

---

## SECTION 2 — {SECTION NAME, ALL CAPS}

| # | Test | Expected | Result | Notes |
|---|------|----------|--------|-------|
| 2.1 | {Action to take} | {What should happen} | | |
```

## Non-negotiable rules

1. **H1 title** must be exactly `# {App Name} v{Version} — QA Plan`. This is parsed as the display name of the run — get the app name and version right, ask if either is missing rather than guessing.
2. **Pre-flight checklist** must start with the literal line `**Before starting QA:**` immediately followed by a `- [ ]` Markdown checklist. This is tracked separately from the numbered tests (checked/unchecked only, no pass/fail).
3. **Section headers** must be `## SECTION N — TITLE`, with the title in ALL CAPS after the em dash. Section numbering is sequential (1, 2, 3...). This drives the app's section grouping and navigation — don't skip numbers or reuse them.
4. **Test IDs** are `{section}.{item}` — e.g. `1.1`, `1.2`, `2.1` — sequential within a section, restarting at `.1` for every new section.
5. **Table columns**, in this exact order: `# | Test | Expected | Result | Notes`. Always leave **Result** and **Notes** blank — PunchList populates those during the actual QA run. Never fill in a Result or Notes value when generating the plan.
6. **One action, one expected outcome per row.** If a test genuinely needs multiple steps, number them within the "Test" cell (e.g. "1. Open Settings 2. Toggle Dark Mode") rather than writing a vague row like "verify settings work correctly."
7. **No nested tables, no merged cells, no HTML** — plain Markdown tables only. PunchList's parser doesn't handle any of these.
8. **Group sections by how a user would walk through the app** (by screen or feature area), not by how it was built or by engineering task. A tester should be able to follow the sections in order and naturally move through the app.

## Generating a good plan, not just a valid one

- Ask (or infer from context) what changed since the last release if this is a "new features only" pass, versus a full pre-release pass covering everything. State the scope explicitly in the italic subtitle line under the title.
- Keep every test row atomic and directly actionable — a tester should read one row, do the one thing, and know immediately whether it passed. Avoid vague rows like "check that the UI looks right"; be specific about what to look for.
- Include a pre-flight checklist covering anything that needs to be true before testing starts — correct build/version installed, test data prepared, other conflicting apps closed, permissions granted, etc. **Default to including one, and briefly explain what it is and why in plain terms when you do** — a first-time user may not know the term "pre-flight checklist" well enough to make an informed yes/no choice before seeing an example. Something like: "I've included a pre-flight checklist — a short list of setup steps to confirm before testing starts (e.g. correct build installed, test data ready). Let me know if you'd rather skip that and just get the numbered tests." This gives them the vocabulary and reasoning to opt out on a follow-up request, rather than asking an unexplained yes/no question before they have context for it.
- Name the output file `{APP}-v{VERSION}-QA-PLAN.md` (e.g. `TASKFLOW-v1_2-QA-PLAN.md`) unless the user specifies otherwise.
- This is a file deliverable, not inline chat content — produce the actual `.md` file for download/import, don't just paste the plan into the conversation.

## Reference example

See `SAMPLE-QA-PASS-EXAMPLE.md` for a complete, correctly-formatted plan (a fictional task-management app, three sections, five-ish tests per section) demonstrating every rule above in practice.