PunchList User Guide
Covers PunchList v1.0
QA tracking that never loses a pass.
What PunchList Does
PunchList tracks QA test passes for your apps — Pass, Fail, Skip, or Pending on every test, with notes and screenshots attached where you need them. It's built for the vibe coding era, but it works with any workflow: whether you're building with an AI coding assistant or the traditional way, you can have your favorite AI tool generate a QA plan, import it, and start testing.
Everything you do in PunchList is saved automatically — including across a crash. Nothing gets lost.
On first launch, PunchList seeds one sample tracked app with a sample run already populated, so there's something real to explore right away. It's safe to delete once you're ready to add your own.
Getting Started
1. Set up your AI tool (recommended, takes a minute)
Before asking an AI for a QA plan, give it the format it needs to produce a file PunchList can actually import. Open Settings → Skills (or the Get an AI Skill link on the welcome screen) and pick the option that matches your tool:
- Using Claude? Download the pre-built Claude Skill package — it's already zipped correctly. Upload it directly at claude.ai → Settings → Skills → + Upload skill, then toggle it on. From then on, just ask Claude for a QA plan in any chat and it already knows the exact format.
- If your download opens as a folder instead of staying a
.zip(this happens automatically in some browsers, especially Safari): right-click the folder → Compress, and upload the resulting.zipinstead.
- If your download opens as a folder instead of staying a
- Using ChatGPT, OpenCode, or something else? Download the plain skill instructions file and paste its contents into your tool as custom instructions, a system prompt, or a project-level rule — however that tool lets you set standing context. Then just ask for a QA plan as usual.
- Writing a plan by hand instead? Download the blank template and fill it in directly — no AI needed at all.
Do this once per AI tool you use; you won't need to repeat it for every plan afterward.
2. Add an app
From the Home screen, click Add Your First App (or New Application in the sidebar, or ⌘⇧N). Give it a name, an optional description, and an icon — either upload an image or extract one directly from an existing .app bundle. Icons are automatically smoothed for a clean, crisp look at every size.
3. Get a QA plan
Now that your AI tool knows the format, just ask for one — describe your app and ask for a QA plan, the same way you'd ask for anything else. Prefer the traditional route? Give your AI tool a description of your app and ask it to come up with a test schedule; if it's using the skill from step 1, the output will already be in the right shape to import.
4. Import and start testing
From an app's detail page, click New Run, then either Import from .md File or choose a saved plan from your Plan Library. You can also start a new run scoped to a specific version directly from within that version's expanded group. PunchList parses the plan into sections and numbered tests, ready to work through.
Running a QA Pass
Each test row shows the test title, expected result, and four status options: Pass, Fail, Skip, Pending. Every run starts with all tests set to Pending.
Keyboard shortcuts
PunchList is built to be run without touching the mouse:
| Key | Action |
|---|---|
1 |
Mark focused test Pass |
2 |
Mark focused test Fail |
3 |
Mark focused test Skip |
4 |
Mark focused test Pending |
N |
Toggle Side Notes for the focused test |
Tab / Shift-Tab |
Move focus to next/previous test |
↑ / ↓ |
Move focus to previous/next test |
⌘N |
New run |
⌘⇧N |
New tracked app |
⌘F |
Focus the search field |
⌘⇧L |
Export diagnostic log |
⌘, |
Preferences |
Delete |
Delete the selected item, with confirmation |
Esc |
Close the open panel or dialog |
Focus is remembered as you navigate — the currently focused row is always clearly highlighted, and keyboard navigation reliably reaches every row, including the very first and very last in a long list.
Notes and attachments
Every test row has a notes field for quick context. On a Fail, you can also attach a screenshot — drag a file onto the row, use the file picker, or copy an image and paste it directly with ⌘V. Attached screenshots can be removed at any time from the row.
Side Notes
Side Notes is a separate running log for the whole run, not tied to pass/fail status — use it to jot context on any test at any time, including tests that already passed, or add a general note not tied to any specific test.
Click Side Note on any row, press N on a focused row, or use the toolbar button to open the panel. Clicking Side Note on a different row switches the panel to that row and keeps it open; clicking the row that's already active closes it — the panel always follows whatever you're currently working on. It slides out as a docked panel you can keep open while you work, or pop out into its own floating window if your screen is tight — reattaching it returns you right to where you left off.
Pre-flight checklist
If your plan includes a pre-flight checklist (setup steps to confirm before testing begins), it appears at the top of the run as a separate checklist, tracked independently from the numbered tests. Collapse it once you've confirmed everything — it stays full-width and just tucks its items away, ready to reopen anytime. You can also turn pre-flight display on or off globally in Preferences, or per run.
When a Test Fails
Generate a retest
Once you've found failures, click Generate Retest on the run. This creates a new run containing only the failed (and optionally skipped) tests, reset to Pending — so you can quickly re-verify just what broke, without re-running the entire plan. The retest run clearly shows a "Retest of [run]" link back to where it came from — click it to jump straight to the original. The original run is never modified.
Copy as a GitHub issue
If you want to turn a failure into a bug report, enable Copy as GitHub Issue in Preferences. This adds a one-click action on failed rows that copies the test's title, expected result, and notes formatted as ready-to-paste issue text.
Reusing Plans
Any imported plan can be saved as a template from the Plan Library. Starting a new run from a template lets you edit the plan before the run begins — useful when testing a new version of the same app with mostly the same test list. Each run created this way is still independent; editing or reusing a template later doesn't affect runs already created from it.
Tracking Progress
App Detail page
Selecting an app shows its full history: total runs, latest status, and every version group, expandable to see individual passes within that version. The most recent version is expanded by default, so your current work is always visible right away — older versions stay tucked away until you need them. Each run shows Edit/View, Delete, and Re-run actions.
A dedicated Analytics view — pass-rate trends and recurring-failure detection across your run history — is planned for a future update.
Home screen and sidebar
The Home screen shows your tracked apps as cards — sorted by most recent activity — with a version and run label together, a labeled test count, and a segmented status bar breaking down Pass/Fail/Skip/Pending at a glance. Below that, a Recent Runs list spans every app.
The sidebar list is sorted alphabetically, so it stays a stable, predictable place to navigate from. Each app shows a small colored status dot — hover over it to see what it means. Right-click any app row for Delete and other actions.
Exporting
Every run can be exported three ways, via dedicated buttons in the run toolbar:
- Markdown (.md) — a Fail/Pending summary, in plain text. Disabled if the run has any attached screenshots, since Markdown can't carry images.
- JSON — a full, lossless dump of the run's data.
- PDF — a formatted report including any attached screenshots, embedded inline.
AI Skills — Quick Reference
Full setup instructions are in Getting Started above. Once set up, you can always come back to Settings → Skills to re-download any of the files, or the welcome screen's Get an AI Skill link (Help menu → Re-read First Run brings that screen back anytime).
More platforms, a longer install walkthrough, and future updates live at getochre.app/punchlist.php.
Preferences
Open with ⌘,. Three tabs:
- General — appearance (System/Light/Dark), Copy-as-GitHub-Issue toggle, pre-flight checklist default
- Skills — the bundled AI skill files, described above, browsable directly on the tab
- Data — where your data lives and how to manage it (below)
Storage and sync
PunchList stores everything in a single .punchlistlib bundle file. By default it lives locally, but you can move it to a cloud-synced folder (like iCloud Drive) to sync your data across Macs — the same mechanism used across the Ochre app suite. If you've moved it and want to bring it back, Move Library to Default Location returns it to the standard system location, safely.
If you need a clean slate, Reset to Defaults wipes all tracked apps, runs, templates, and preferences and starts fresh, including reseeding the sample app and welcome screen. This is destructive and requires explicit confirmation — it's intentionally worded and styled differently from the Move Library actions so the two are never confused.
Diagnostics
⌘⇧L opens a save dialog for a privacy-safe diagnostic log — aggregate counts, app version, and preference values only. It never includes app names, run names, test content, file paths, or attachment contents.
Help Menu
- PunchList Guide — opens this guide in your browser
- Re-read First Run — brings back the welcome screen anytime you want to see it again
Support
PunchList is free, built by Ochre. For the latest version of this guide, visit getochre.app/guides/guide-punchlist.php. For the PunchList product page, downloads, and AI skill files, visit getochre.app/punchlist.php. Questions, feedback, or bug reports are welcome via getochre.app.
PunchList — QA tracking that never loses a pass.