메뉴
After a PRD, spec, or plan, before implementation: hunt perceived-quality pitfalls (silent failures, missing loading/empty states, error recovery, state drift) that make a product feel cheap. Complements pitfall-verification.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
Adapt an existing project to the Superpowers + GStack workflow. Analyzes the project, identifies gaps, updates CLAUDE.md routing without losing existing content, and sets up required structure.
Generate a tailored CLAUDE.md with routing rules for the Superpowers + GStack workflow. Asks about project type, evaluates relevant skills from both frameworks, and produces a project-specific routing plan.
After any PRD, spec, plan, or code change: verify artifact-specific pitfalls don't apply before declaring done. For ship-worthy changes, auto-chains Codex + a third model house + adversarial synthesis.
Auto-advance a multi-phase plan: dispatch a subagent per phase, chain /review + /pitfall-verification at each boundary, stop on actionable findings. Use for "autoimplement", "run this plan end-to-end", "auto-advance phases".
Pure dispatcher: picks the right E2E executor for a Swift test request from context (platform × intent × verification kind) and hands off. Routes to the scaffold/MCP-sim/QA/design-review skills.
Generate beautiful, pedagogical HTML companions for superpowers-gstack MD artifacts (design docs, handoffs, plans). Auto-opens via --open; generates per-directory dashboards. Triggered manually or via PostToolUse hook.
SOC 직업 분류 기준
| name | quality-review |
| description | After a PRD, spec, or plan, before implementation: hunt perceived-quality pitfalls (silent failures, missing loading/empty states, error recovery, state drift) that make a product feel cheap. Complements pitfall-verification. |
Use this skill after finishing a PRD, spec, or implementation plan — before implementation starts. It is NOT a bug hunt. It is a targeted check that the artifact, if shipped as written, will feel like a premium product — on the level of CleanMyMac, Raycast, Linear, Things, Stripe Dashboard — and not like a hobby project.
Invoke with: /superpowers-gstack:quality-review
Automatically after completing:
writing-specs, writing-plans, plan-design-review, plan-eng-review, or any planning skill that produces an artifact ready to hand off to implementationRun once before implementation. Re-run after substantial spec/plan revisions.
quality-review is complementary, not overlapping, with pitfall-verification:
| Skill | Lens | Question |
|---|---|---|
pitfall-verification | Correctness | "Will this work?" (bugs, security, contracts, edge cases) |
quality-review | Perceived quality | "Will this feel good?" (silent failures, loading, empty/error states, polish) |
Recommended flow on a fresh artifact:
pitfall-verification → fix bugsquality-review → fix feelwriting-plans / implementationBoth should be run. They catch different classes of issue.
PlanStore actually does today.These are starting points, not exhaustive. Add domain-specific quality risks as they surface.
For each category: state the question, locate the risk surface in the artifact, verify by reading the code, and report N/A | HANDLED | NOT HANDLED — proposed fix.
Where in the flow can something fail without the user being told? AI calls returning nothing, parse errors that get "abandoned silently", retry loops with no UI signal, swallowed exceptions. Silent failure = user thinks the app is broken.
Risk surfaces: any try/catch with empty catch, any optional unwrap that defaults to "", any AI call without an error path.
Is there any operation that takes >500ms without a spinner, skeleton, progress text, or cancel button? Specifically check: AI calls, file I/O, shell commands, scan/index operations, network requests.
Risk surfaces: spec sections that describe an operation without a "during" UI state.
What does the user see the first time a list/view is empty? A spec that does not define empty state = generic "no items" = bad first impression. Premium apps treat empty state as a teaching moment (Linear's empty inbox, Things' empty Today).
Risk surfaces: any new list/grid/table view in the spec.
When something fails, how does the user get back on rails? Inline banner with retry? Toast? Blank screen? Each error path should have an explicit recovery action — not just "show error".
Risk surfaces: every failure mode listed in the spec; every code path that throws.
If the app's stored state and reality (filesystem, system settings, external API) can diverge, how is reconciliation handled? Classic example: user changes something outside the app, app still shows the old state.
Risk surfaces: any feature that mirrors external state (file watchers, system prefs, external APIs, login items, calendar events).
Can an undo/revert/overwrite operation, run without a warning, destroy the user's manual edits? Pay special attention to snapshot-based revert flows and auto-fix that overwrites files.
Risk surfaces: any "revert", "restore", "auto-fix", "regenerate" action; any operation that writes to a path the user could have edited.
Are there features that are technically implemented but nobody will find? Hidden tab, audit log without UI, keyboard shortcut without a menu item, settings panel buried three levels deep.
Risk surfaces: every feature in the spec — ask "how would a new user encounter this?"
If the app has workspaces, profiles, accounts, projects: is the new state correctly scoped, or is it global and leaking between tenants? This is one of the highest-impact pitfalls — global state in a workspaced app breaks the mental model on day one.
Risk surfaces: any *.shared singleton, any ~/Library/Application Support/<app>/*.json path that isn't workspace-scoped, any UserDefaults.standard write.
Is time-dependent state (snooze, cache expiry, scheduled actions, "remind me in 1h") re-evaluated during an active session, or only at app launch? "Only on launch" = app feels lazy. Premium apps re-check on a timer or via system notifications.
Risk surfaces: any feature involving time, expiry, or scheduling.
For macOS: ⌘W (close window), ⌘1-9 (tab switching), ⌘↩ (primary action), Space (preview), Esc (dismiss) — are platform conventions respected? For web: tab order, focus ring, Esc-to-dismiss, Enter-to-confirm? For iOS: swipe-to-go-back, edge gestures?
Risk surfaces: any new modal, sheet, list, or view introduced by the spec.
Does the spec rely on default framework animations (SwiftUI default, CSS default — both feel generic), or specify named easing (.spring, .snappy, cubic-bezier(...)) with rationale? Premium apps have signature motion. Generic ease-in-out reads as "AI-generated".
Risk surfaces: any sheet present/dismiss, any list reorder, any state change that is visible.
If the artifact involves LLM calls:
```json ... ```) and schema validation explicit?If unsure of current best practice — use WebSearch on Anthropic docs.
Risk surfaces: any AI call in the spec.
If the app requires sudo, admin auth, system permissions (Full Disk Access, Accessibility, etc): is the flow framed as deliberate design — explanation sheet + consent + clear "why we need this" — or just a toast that pops up and disappears? "Just a toast" = feels cheap.
Risk surfaces: any TCC permission, any osascript with admin privileges, any Authorization Services call.
Does the spec use LocalizedStringKey (SwiftUI) / t() / equivalent for user-facing strings, or are strings hardcoded? Even if the app ships English-only today, hardcoded strings = future tech debt and immediate inconsistency with the rest of the codebase if it already localizes.
Risk surfaces: every user-facing string in the spec — dialog titles, button labels, error messages, empty-state copy.
If the spec introduces a new list view, is sort order explicitly defined? Unspecified = whatever the underlying collection happens to yield = unpredictable UX. Premium apps always specify (most recent first, alphabetical, manual drag, etc).
Risk surfaces: every new list/table introduced by the spec.
The 15 above are the generic perceived-quality surface. Add domain-specific quality risks before running:
--help quality, color in pipes, exit codes, progress on stderr, man page presenceUse the existing peer apps in the user's domain as the comparison baseline.
For each category:
PlanStore", read PlanStore.swift to confirm the extension is sane.N/A (with reason) / HANDLED (point to where) / NOT HANDLED — proposed fix (concrete, file/section-anchored).Concrete findings only. Never vague advice like "consider improving error handling". Every NOT HANDLED finding must include a proposed fix that names a file, a function, or a spec section.
Quality review —
CRITICAL (will make the app feel broken on first use):
- Q<N>. <one-line finding> — <risk surface> → <concrete fix with file/section reference>
- ...
SIGNIFICANT (erodes quality over time):
- Q<N>. <finding> → <fix>
- ...
POLISH (premium-feel gap, but not blocking):
- Q<N>. <finding> → <fix>
- ...
Peer comparison: <which premium peer was used as the bar, and how this artifact stacks up>
Verdict: SHIP-READY | NEEDS PATCH (critical issues found) | NEEDS POLISH (significant issues found)
If SHIP-READY: hand off to implementation.
If NEEDS PATCH: fix critical findings, re-run quality-review.
If NEEDS POLISH: surface to user with explicit choice — fix now, or defer with a tracked debt note.
Be honest about severity. A POLISH finding should not be elevated to CRITICAL just to force action.
Q8. Per-workspace isolation missing. PlanStore.shared is a global singleton
persisting to a single plan-cards.json. The app has workspaces, and all other
state objects (HealthEngine, AIChatViewModel) are workspace-scoped. Plan Cards
generated in workspace "Home" will appear in workspace "client-project". This
breaks the mental model on first multi-workspace use.
Risk surface: spec §4.2 ("Persistence"); code at PlanStore.swift:14.
Fix: persist to ~/Library/Application Support/<app>/workspaces/<workspace-id>/plan-cards.json.
Make PlanStore workspace-injected, not a singleton. Update spec §4.2 to specify
the path template and migration plan for existing global state.
That is the bar. File path, line number, peer-app comparison where relevant, concrete fix.
pitfall-verification.cso.design-review (live) or plan-design-review (plan).plan-devex-review.It is the perceived-quality gate between "spec written" and "implementation begins". Catch the cheap-feeling decisions before they ship.