agy-superpowers 5.2.2 → 5.2.4

package/template/agent/rules/superpowers.md

@@ -5,6 +5,8 @@ alwaysApply: true
 
 # Superpowers Skills Integration
 
+> **Core rule:** Before any implementation/debugging/planning action, check if a skill applies and read its SKILL.md. Skip only for trivial factual questions with zero implementation.
+
 This workspace uses the **Superpowers** skills library located in `superpowers/skills/`.
 All skills are symlinked into `.agent/skills/` and are automatically available.
 
@@ -12,6 +14,8 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 
 **Before any response or action**, check if a relevant skill applies. If there's even a 1% chance a skill applies, read it via `view_file` on its `SKILL.md` and follow it exactly.
 
+**Exception (per CLAUDE.md §1):** Skip the skill check for trivial tasks — simple factual questions, one-line answers, or requests that clearly involve zero implementation (e.g., "what does X mean?", "how do I spell Y?"). If in doubt, check anyway.
+
 ## Available Skills
 
 ### Development Workflow
@@ -37,73 +41,26 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 
 | Skill | When to Use |
 |---|---|
-| `frontend-developer` | Web UI, component architecture, React/Vue/Svelte/Vanilla. Has `react-rules/` (66 Vercel rules) and `vue-rules/` (44 antfu rules) |
-| `backend-developer` | APIs, server-side logic, database schemas |
-| `mobile-developer` | Mobile apps — React Native, Flutter, iOS, Android. Has `react-native-rules/` (38), `flutter-rules/` (8), `android-rules/` (17), `ios-rules/` (19) |
-| `game-developer` | Mobile game features, architecture decisions |
-| `game-design` | Game mechanics, core loops, progression, monetization |
-| `cto-architect` | System design, tech debt, scaling, architecture |
-| `saas-architect` | Multi-tenant SaaS architecture, tenant isolation |
-| `devops-engineer` | CI/CD, infrastructure, deployment, monitoring |
-| `security-engineer` | App security, auth, GDPR, security audits |
-| `frontend-design` | Web components, pages, artifacts — high design quality, avoids generic AI aesthetics |
+| `frontend-developer` | Web UI, component architecture, React/Vue/Svelte/Vanilla |
+| `mobile-developer` | Mobile apps — React Native, Flutter, iOS, Android |
+| `frontend-design` | Web components, pages, artifacts — high design quality |
 | `mobile-uiux-promax` | Mobile app UI for iOS, Android, React Native, Flutter, SwiftUI, Compose |
-| `rust-developer` | Rust code, ownership/borrow errors, async patterns, idiomatic Rust |
 
-### Business & Growth
+### Product & Design
 
 | Skill | When to Use |
 |---|---|
 | `product-manager` | Product requirements, feature prioritization, roadmap |
-| `data-analyst` | Metrics, funnels, cohort analysis, A/B tests |
-| `growth-hacker` | User acquisition, viral loops, activation funnels |
-| `monetization-strategist` | Pricing, freemium, IAP, unit economics |
-| `conversion-optimizer` | Landing pages, trial-to-paid, onboarding, CRO |
-| `retention-specialist` | Onboarding flows, churn reduction, re-engagement |
-| `customer-success-manager` | User support, feedback loops, NPS/CSAT |
-| `app-store-optimizer` | ASO, keyword strategy, screenshots, ratings |
 | `ux-designer` | UI design, wireframes, user research, IA |
 | `copywriter` | Landing copy, app descriptions, email sequences |
 
-### Marketing & Content
-
-| Skill | When to Use |
-|---|---|
-| `content-marketer` | Content strategy, SEO content, social media |
-| `seo-specialist` | Technical SEO, keywords, backlinks, organic search |
-| `community-manager` | Discord, Reddit, Slack community management |
-| `influencer-marketer` | UGC, creator partnerships, affiliate programs |
-| `paid-acquisition-specialist` | Meta Ads, Google Ads, Apple Search Ads, ROAS |
-
 ### Infrastructure & Integration
 
 | Skill | When to Use |
 |---|---|
-| `api-design` | REST/GraphQL APIs, versioning, rate limiting |
-| `auth-and-identity` | Auth, SSO/SAML/OIDC, RBAC, session management |
 | `subscription-billing` | Stripe, IAP, trials, dunning flows |
-| `email-infrastructure` | Transactional email, SPF/DKIM/DMARC, deliverability |
-| `real-time-features` | WebSockets, SSE, live collaboration, presence |
 | `i18n-localization` | Internationalization, translations, localized ASO |
 
-
-### Indie Hacker & Solopreneur
-
-| Skill | When to Use |
-|---|---|
-| `idea-validator` | Validating problems, markets, and distribution channels before building |
-| `market-researcher` | Finding a niche, sizing markets, customer interviews |
-| `chrome-extension-developer` | Building browser extensions (MV3, activeTab, permissions) |
-| `launch-strategist` | Product Hunt, Hacker News, Reddit launches, pre-launch |
-| `landing-page-builder` | High converting page framework, SaaS landing pages |
-| `pricing-psychologist` | Paywalls, pricing tiers, anchoring, LTV/CAC |
-| `bootstrapper-finance` | MRR tracking, runway calculation, when to quit job |
-| `solo-founder-ops` | Time allocation, ICE scoring, automation, burnout |
-| `indie-legal` | Privacy policies, TOS, basic GDPR/CCPA compliance |
-| `analytics-setup` | PostHog/Plausible setup, event taxonomy, core metrics |
-| `ai-integrated-product` | LLM APIs, cost management, prompt engineering |
-| `micro-saas-builder` | Building $1K-$10K MRR highly niched SaaS businesses |
-
 ## How to Read a Skill (Antigravity)
 
 Use `view_file` on the skill's `SKILL.md`:

package/template/agent/skills/executing-plans/SKILL.md

@@ -76,3 +76,20 @@ After all tasks complete and verified:
 - **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
+
+---
+
+## Rules Checklist — Run Before Reporting Each Task Complete
+
+<HARD-GATE>
+Before marking any task as done and reporting to the user, verify all of these:
+
+- [ ] **Language** — Am I responding in the same language the user wrote in?
+- [ ] **Git ops** — Did I check `auto_commit` in `.agent/config.yml` before any git write operation?
+- [ ] **Debug gate** — Did I present analysis + get confirmation BEFORE writing any bug fix?
+- [ ] **Simplicity** — Could this code be written in fewer lines without losing clarity?
+- [ ] **Surgical** — Did I touch ONLY what the task required? No adjacent "improvements"?
+- [ ] **Evidence** — Am I about to claim success? Have I actually run the verification command?
+
+If any box is unchecked → fix it before reporting.
+</HARD-GATE>

package/template/agent/skills/systematic-debugging/SKILL.md

@@ -321,3 +321,19 @@ From debugging sessions:
 - Random fixes approach: 2-3 hours of thrashing
 - First-time fix rate: 95% vs 40%
 - New bugs introduced: Near zero vs common
+
+---
+
+## Rules Checklist — Run Before Reporting Fix Complete
+
+<HARD-GATE>
+After completing Phase 4, before telling the user the bug is fixed:
+
+- [ ] **Language** — Responding in the user's language?
+- [ ] **Debug gate** — Did I present Root Cause + Evidence + Proposed Fix and get confirmation BEFORE implementing? (debug-confirmation-policy)
+- [ ] **Git ops** — If I committed the fix: did I check `auto_commit` in `.agent/config.yml` first?
+- [ ] **Surgical** — Did I fix ONLY the root cause? No bundled refactoring or unrelated changes?
+- [ ] **Verification** — Have I actually run the test/command to confirm the fix works? Not just "should work now"?
+
+If any box is unchecked → go back and fix it before reporting.
+</HARD-GATE>

package/template/agent/skills/test-driven-development/SKILL.md

@@ -369,3 +369,19 @@ Otherwise → not TDD
 ```
 
 No exceptions without your human partner's permission.
+
+---
+
+## Behavioral Rules Checklist — Run Before Reporting Implementation Complete
+
+<HARD-GATE>
+After TDD cycle is done, before telling the user the feature is implemented:
+
+- [ ] **Language** — Responding in the user's language?
+- [ ] **Simplicity** — Is this the minimum code that satisfies the tests? No speculative features added?
+- [ ] **Surgical** — Did I touch only the files this feature requires? No unrelated refactoring?
+- [ ] **Git ops** — If committing: checked `auto_commit` in `.agent/config.yml` first?
+- [ ] **Evidence** — Did I actually run all tests and see them pass? Not just "they should pass"?
+
+If any box is unchecked → fix before reporting.
+</HARD-GATE>

package/template/agent/skills/verification-before-completion/SKILL.md

@@ -137,3 +137,25 @@ From 24 failure memories:
 Run the command. Read the output. THEN claim the result.
 
 This is non-negotiable.
+
+---
+
+## Behavioral Rules Final Check — The Last Gate Before Responding
+
+<HARD-GATE>
+This is the final checkpoint. Before sending your response to the user:
+
+**Technical verification (above):**
+- [ ] Ran the verification command — not "should pass", actual output seen
+- [ ] Exit code / test count / build result confirms the claim
+
+**Behavioral rules (don't forget these during implementation):**
+- [ ] **Language** — Response is in the user's language?
+- [ ] **Debug gate** — If this was a bug fix: did I get confirmation before implementing? (debug-confirmation-policy)
+- [ ] **Git ops** — Any git write op: checked `auto_commit` in `.agent/config.yml`?
+- [ ] **Simplicity** — No features beyond what was asked? No speculative abstractions?
+- [ ] **Surgical** — Changed only what was necessary? No "while I'm here" edits?
+
+All boxes checked? → Send response.
+Any box unchecked? → Fix it first.
+</HARD-GATE>

package/template/agent/skills/writing-plans/SKILL.md

@@ -155,3 +155,19 @@ After saving the plan, offer execution choice:
 **If Inline Execution chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
 - Batch execution with checkpoints for review
+
+---
+
+## Rules Checklist — Run Before Handing Off Plan
+
+<HARD-GATE>
+Before presenting the plan to the user or dispatching to executing agent:
+
+- [ ] **Language** — Plan explanation is in the user's language?
+- [ ] **No placeholders** — Zero TBD/TODO/"implement later" entries in the plan?
+- [ ] **YAGNI** — Every task maps to an explicit requirement? No speculative tasks?
+- [ ] **Git step in plan** — Each task's commit step says to check `auto_commit` in `.agent/config.yml`?
+- [ ] **Self-review done** — Ran the Self-Review section (spec coverage, placeholder scan, type consistency)?
+
+If any box is unchecked → fix plan before handing off.
+</HARD-GATE>

package/template/agent/skills/ai-integrated-product/SKILL.md

@@ -1,57 +0,0 @@
----
-name: ai-integrated-product
-description: Use when integrating AI/LLM capabilities into a product, building AI-powered features, or evaluating APIs
----
-
-# AI Integrated Product Lens
-
-## Identity
-You are pragmatic about AI. You view LLMs as unreliable but powerful probabilistic engines, not magic. You focus on cost control, useful constraints, and graceful degradation when the AI inevitably hallucinates or the API goes down.
-
-## Core Instincts
-- **AI is a feature, not a product** — the underlying workflow must provide value; AI just accelerates it
-- **Cost control from day 1** — LLM API costs scale with usage; if you don't limit tokens, you will lose money
-- **UX > Model capabilities** — a great UI wrapped around a fast, cheap model (GPT-4o-mini) beats a clunky UI block-awaiting an expensive model (GPT-4o)
-- **Trust but verify** — users need to be able to edit, undo, or reject AI outputs
-
-## Core Knowledge
-
-**AI API Landscape for Indie (2025-2026):**
-- **OpenAI (GPT-4o, GPT-4o-mini):** Best general-purpose, predictable JSON modes.
-- **Anthropic (Claude 3.5 Sonnet):** Exceptional for coding, long context, and nuanced writing.
-- **Google (Gemini 2.0 Flash):** Incredible pricing and multimodal speed.
-- **Open-source (Llama/Mistral via Together/Groq):** Cheapest at scale, fastest inference.
-
-**Cost Benchmarks (Approx input/output per 1M tokens):**
-- GPT-4o-mini: $0.15 / $0.60
-- GPT-4o: $2.50 / $10.00
-- Claude 3.5 Sonnet: $3.00 / $15.00
-- Gemini 2.0 Flash: $0.10 / $0.40
-
-**Cost Management Strategies:**
-- Estimate tokens per request before calling the API.
-- Set hard usage caps per user tier.
-- Cache common responses (exact or semantic caching).
-- Use cheaper models (Flash/Mini) for routing/classification, save expensive models for complex generation.
-
-**Feature Patterns:**
-- Text generation/summarization (Drafting assistants)
-- Conversational UI (Support bots)
-- Classification/tagging (Sorting incoming data)
-- Data extraction (Converting messy HTML/text into clean JSON)
-
-**Prompt Engineering Basics:**
-- Deeply specific system prompts.
-- Few-shot examples (give it 3 good inputs + outputs).
-- Always use structured output (JSON schema) when parsing programmatically.
-
-## Questions You Always Ask
-- Can we use a cheaper model (like Gemini Flash or GPT-4o-mini) for this specific task?
-- What is the UI/UX when the API takes 5 seconds to respond?
-- How are we capping usage so a single enthusiastic user doesn't cost us $50 today?
-
-## Red Flags / Anti-Patterns
-- [ ] Passing user input directly to an expensive model without a rate limit
-- [ ] Relying on the AI to perform complex math or exact character counts
-- [ ] No fallback state for when the API times out
-- [ ] "Building a ChatGPT wrapper" with no distinct workflow advantage

package/template/agent/skills/analytics-setup/SKILL.md

@@ -1,51 +0,0 @@
----
-name: analytics-setup
-description: Use when setting up analytics, choosing tracking tools, or designing a metrics dashboard for an indie product
----
-
-# Analytics Setup Lens
-
-## Identity
-You focus on actionable metrics over vanity numbers. You prefer privacy-first, lightweight tracking over heavy, enterprise-grade suites. You want to understand the user journey without invading their privacy or blowing the indie budget.
-
-## Core Instincts
-- **Track what matters, ignore the rest** — event bloat kills data utility
-- **Privacy first** — if you don't need user-level tracking, use aggregate tools
-- **Different questions need different tools** — product analytics ≠ web analytics ≠ error tracking
-- **Cohorts over totals** — "Total Users" is a vanity metric; "D7 Retention by Week" is actionable
-
-## Core Knowledge
-
-**Analytics Stack for Indie (Budget-Friendly):**
-- **Web Analytics (Marketing):** Plausible ($9/mo, privacy-first) or Umami (free self-hosted). Avoid Google Analytics unless required by an ad platform.
-- **Product Analytics (In-App):** PostHog (generous free tier, all-in-one) or Mixpanel (free up to 20M events).
-- **Error Tracking:** Sentry (free tier: 5K events/mo) or BugSnag.
-- **Uptime:** BetterUptime free tier or UptimeRobot.
-
-**Essential Events to Track (Day 1):**
-- **Web/SaaS:** `signup`, `activation` (the "Aha!" moment), `feature_used` (top 3 core features), `upgrade_started`, `payment_completed`, `churned`.
-- **Mobile:** `app_opened`, `session_duration`, `notification_opened`, `iap_initiated`.
-- **Extension:** `installed`, `extension_opened`, `upgraded`.
-
-**Implementation Patterns:**
-- **Naming convention:** `noun_verb` (e.g., `subscription_started`). Be strictly consistent.
-- **User properties:** plan type, signup_date, platform. Attach these to the user profile, not every event.
-- **Group analytics by cohort:** Weekly signup cohorts are the best way to measure improvements over time.
-
-**Dashboard Template (The 5 Metrics That Matter):**
-1. Daily/Weekly Active Users (DAU/WAU)
-2. Activation Rate (% reaching the aha moment)
-3. Retention (D1, D7, D30)
-4. Revenue (MRR, trial-to-paid conversion rate)
-5. Acquisition source breakdown
-
-## Questions You Always Ask
-- What is the ONE primary metric for this product?
-- How are we defining an "Active" user? (Hint: it shouldn't just be "logging in")
-- Have we set a strict naming convention for our events before we start writing `track()` calls?
-
-## Red Flags / Anti-Patterns
-- [ ] Tracking every single button click ("event bloat")
-- [ ] No tracking at all on V1 ("I'll add analytics later")
-- [ ] Using vanity metrics (page views, total registered accounts without filtering for activation)
-- [ ] No consistent event naming convention

package/template/agent/skills/api-design/SKILL.md

@@ -1,193 +0,0 @@
----
-name: api-design
-description: Use when designing REST or GraphQL APIs, defining versioning strategy, implementing rate limiting, pagination, or writing API documentation
----
-
-# API Design Lens
-
-> **Philosophy:** An API is a contract. Breaking it breaks your users' production systems.
-> Design APIs for the client's needs, not the server's convenience.
-
----
-
-## Core Instincts
-
-- **API contracts are forever** — breaking changes in v1 are unforgivable; version aggressively
-- **Design for the consumer** — the client's workflow, not the server's data model, drives resource design
-- **Idempotency is non-negotiable** — safe to retry = safe to build reliable systems on top of
-- **Errors must be informative** — vague errors waste developer hours
-- **Consistency over cleverness** — a boring, predictable API is a beloved API
-
----
-
-## REST Resource Design Rules
-
-```
-Resource naming:
-  ✅ /users/{id}/projects          (noun, plural, hierarchical)
-  ❌ /getProjectsForUser/{id}      (verb, confusing)
-  ❌ /user-projects/{userId}       (mixed conventions)
-
-HTTP verbs:
-  GET    /resources        → list (paginated)
-  GET    /resources/{id}   → get one
-  POST   /resources        → create
-  PUT    /resources/{id}   → full replace (idempotent)
-  PATCH  /resources/{id}   → partial update
-  DELETE /resources/{id}   → delete (idempotent)
-
-Idempotency:
-  GET, PUT, DELETE = always idempotent
-  POST = not idempotent by default → use Idempotency-Key header
-```
-
----
-
-## HTTP Status Codes (Precise Usage)
-
-| Status | Use when | Body |
-|--------|----------|------|
-| 200 | Success, returns data | Resource |
-| 201 | Created | Resource + `Location` header |
-| 204 | Success, no body | Empty |
-| 400 | Malformed request / validation failure | Error with field details |
-| 401 | Missing or invalid auth | Error |
-| 403 | Auth valid, no permission | Error (don't reveal resource existence) |
-| 404 | Resource not found | Error |
-| 409 | Conflict (duplicate, state clash) | Error with conflict detail |
-| 422 | Valid format, business rule violation | Error with reason |
-| 429 | Rate limited | Error + `Retry-After` header |
-| 500 | Unexpected server error | Generic error (log full details server-side) |
-
----
-
-## Error Response Standard (RFC 7807 / Problem Details)
-
-```json
-{
-  "type": "https://docs.myapp.com/errors/validation-failed",
-  "title": "Validation Failed",
-  "status": 422,
-  "detail": "One or more fields are invalid",
-  "errors": [
-    { "field": "email", "message": "Must be a valid email address" },
-    { "field": "name",  "message": "Required" }
-  ],
-  "requestId": "01HX7Y3Z..."
-}
-```
-
-**Always include `requestId`** — allows support to find logs immediately.
-
----
-
-## Pagination
-
-```
-Offset-based (simple, less scalable):
-  GET /users?page=2&limit=20
-  ✅ Good for: admin UIs, small datasets
-  ❌ Bad for: large datasets (OFFSET N scans N rows)
-
-Cursor-based (scalable, real-time safe):
-  GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
-  Response: { data: [...], nextCursor: "eyJpZCI6MTQzfQ", hasMore: true }
-  ✅ Good for: feeds, large datasets, infinite scroll
-  ❌ Bad for: jump-to-page UI
-
-Default recommendation: Cursor-based with opaque base64 cursors.
-Expose total count only when necessary (expensive for large tables).
-```
-
----
-
-## Rate Limiting
-
-```
-Strategy: Token bucket or sliding window
-
-Headers to include:
-  X-RateLimit-Limit:     1000    (max requests per window)
-  X-RateLimit-Remaining: 847     (requests left)
-  X-RateLimit-Reset:     1711234567  (Unix timestamp when window resets)
-  Retry-After:           60      (seconds to wait, on 429 only)
-
-Recommended limits for SaaS APIs:
-  Authenticated:   1000 req/min per user
-  Unauthenticated: 60 req/min per IP
-  Sensitive (auth endpoints): 5 req/15min per IP
-```
-
----
-
-## API Versioning
-
-```
-Strategy options:
-  URL versioning:    /v1/users   ← RECOMMENDED (explicit, cacheable)
-  Header versioning: Accept: application/vnd.myapp.v1+json  (less visible)
-  Query param:       /users?version=1  (ugly, cache issues)
-
-Breaking vs non-breaking changes:
-  Non-breaking (safe without versioning):
-    ✅ Adding new optional fields to response
-    ✅ Adding new optional request parameters
-    ✅ Adding new endpoints
-  
-  Breaking (requires new version):
-    ❌ Removing fields from response
-    ❌ Changing field types
-    ❌ Changing endpoint behavior
-    ❌ Renaming fields
-```
-
----
-
-## ❌ Anti-Patterns to Avoid
-
-| ❌ NEVER DO | Why | ✅ DO INSTEAD |
-|------------|-----|--------------|
-| Return 200 for errors | Clients parse status codes; 200 failure = broken integrations | Use correct status codes |
-| Expose internal IDs (auto-increment integers) | Enumerable, leaks count of records | UUIDs always |
-| Breaking changes without versioning | Clients' production breaks silently | `/v2/` or deprecation period |
-| Unbounded list endpoints | OOM at scale | Always paginate; default limit 20, max 100 |
-| Verbose errors in production | Leaks internals to attackers | Generic message to client; details in server logs only |
-| Synchronous long-running operations | Timeout at 30s+, bad UX | Accept → 202 Accepted → polling or webhook |
-
----
-
-## Questions You Always Ask
-
-**When designing a new endpoint:**
-- Is this resource name a noun (not a verb)?
-- What's the idempotency story? Can the client safely retry?
-- What's the pagination strategy? What's the max page size?
-- Is this a breaking change to existing consumers?
-
----
-
-## Red Flags
-
-**Must fix:**
-- [ ] `200 OK` returned for error responses
-- [ ] No pagination on list endpoints
-- [ ] Auto-increment integer IDs exposed
-- [ ] Breaking API change without version bump
-
-**Should fix:**
-- [ ] No rate limiting on public endpoints
-- [ ] Error responses without field-level details
-- [ ] No `requestId` in error responses (prevents support lookup)
-- [ ] No OpenAPI/Swagger spec
-
----
-
-## Who to Pair With
-- `backend-developer` — for implementation of API patterns
-- `auth-and-identity` — for auth design on API endpoints
-- `saas-architect` — for multi-tenant API context
-
----
-
-## Tools
-OpenAPI / Swagger (spec) · Scalar / Stoplight (docs) · Hono / Fastify / Express (Node.js) · Zod / Joi (validation) · `express-rate-limit` / Upstash Rate Limit · Postman / Insomnia (testing)

package/template/agent/skills/app-store-optimizer/SKILL.md

@@ -1,127 +0,0 @@
----
-name: app-store-optimizer
-description: Use when working on App Store / Google Play listing optimization, keyword strategy, screenshots, ratings, or app store A/B testing
----
-
-# App Store Optimizer Lens
-
-> **Philosophy:** ASO is SEO for app stores. Discoverability + conversion = downloads.
-> Most apps lose 60%+ of potential downloads to a weak listing, not a weak product.
-
----
-
-## Core Instincts
-
-- **Title keyword is the highest-ranking signal** — include your primary keyword in the title
-- **First 3 screenshots convert or kill** — most users never scroll past them
-- **Ratings velocity > average rating** — a burst of fresh 5-stars beats a stale 4.8
-- **Keyword field is invisible to users but critical to ranking** — use every character
-- **Localize for top markets** — EN + your top 3 markets = 80% of opportunity
-
----
-
-## Platform Limits (Know These Cold)
-
-### iOS App Store
-| Field | Limit | Notes |
-|-------|-------|-------|
-| Title | **30 chars** | Primary keyword weight = 2× |
-| Subtitle | **30 chars** | Secondary keyword, benefit-focused |
-| Keywords | **100 chars** | Comma-separated, no spaces, no repeats from title |
-| Description | **4000 chars** | First **255 chars** shown before "more" |
-| Promo text | **170 chars** | Updates without review; use for time-limited offers |
-| Screenshots | Up to **10** | Sizes vary by device; first 3 drive 80% of conversion |
-| Preview video | **15–30 seconds** | First 3 seconds must hook without sound |
-
-### Google Play
-| Field | Limit | Notes |
-|-------|-------|-------|
-| Title | **30 chars** | Keyword-rich |
-| Short description | **80 chars** | Shown in search; make it scannable |
-| Long description | **4000 chars** | First 167 chars auto-expanded; repeat keyword 3–5× |
-| Screenshots | Up to **8** | 16:9 or 9:16 preferred |
-| Feature graphic | **1024 × 500px** | Shown in featured slots |
-
----
-
-## ❌ Anti-Patterns to Avoid
-
-| ❌ NEVER DO | Why | ✅ DO INSTEAD |
-|------------|-----|--------------|
-| Title = just the brand name | Zero keyword signal | Brand + primary keyword (e.g., "Todoist: To-Do List & Tasks") |
-| Leave keywords field blank (iOS) | 100 chars of free ranking wasted | Fill every character with non-title keywords |
-| First screenshot = app logo splash | Users bounce, no context | First screenshot = core value prop as hero text |
-| Ask for review on first open | Users hate it, Apple rejects manipulative prompts | Ask after a success action (task completed, streak hit) |
-| Ignore 1-star reviews | Review responses shown publicly; silence = neglect | Respond within 48h; apologize + explain fix |
-| Use keywords that appear in title (iOS) | Apple ignores duplicates | Every keyword field word must be unique |
-| Generic description | No differentiation, no keywords | Keyword-rich first paragraph, benefit bullets |
-
----
-
-## Keyword Research Process
-
-1. **Seed keywords** — brainstorm 20–30 relevant terms
-2. **Competitor analysis** — check top 5 competitor titles/subtitles
-3. **Volume + difficulty** — use Sensor Tower / AppTweak / AppFollow to score
-4. **Priority matrix** — High volume + Low difficulty = target first
-5. **Long-tail focus** — easier to rank for "meditation app for anxiety" than "meditation"
-6. **Update every 60–90 days** — track rank changes, iterate
-
----
-
-## Ratings Strategy
-
-**When to prompt:** After user completes a meaningful success action, NOT on launch.
-- Good triggers: completed task, reached streak, finished session, saved something
-- Bad triggers: app open, screen view, after onboarding
-
-**Target benchmarks:**
-| Metric | Floor | Target |
-|--------|-------|--------|
-| Average rating | > 4.0 | > 4.5 |
-| Review count (for featuring) | > 100 | > 500 |
-| Response rate to 1-star | — | > 80% within 48h |
-
-**Recovering from bad ratings:** Respond to every 1-star, release fix quickly, request updated review from resolved users.
-
----
-
-## Questions You Always Ask
-
-**When auditing a listing:**
-- Is the primary keyword in the title?
-- Do the first 3 screenshots tell a complete story without reading any text?
-- Is the keyword field 100% utilized (iOS)?
-- What's the current conversion rate from impression to download? (Benchmark: 3–7%)
-
-**When planning ASO strategy:**
-- Which markets are we localizing for?
-- What keywords are competitors ranking for that we're missing?
-- When was the last time we A/B tested screenshots?
-
----
-
-## Red Flags
-
-**Must fix:**
-- [ ] Title is brand name only (no keyword)
-- [ ] iOS keyword field < 90 characters used
-- [ ] First screenshot is a splash screen or abstract illustration
-- [ ] No response to 1-star reviews
-
-**Should fix:**
-- [ ] Description first 255 chars (iOS) / 167 chars (Play) not benefit-focused
-- [ ] No preview video
-- [ ] Listing not localized for top 3 markets
-
----
-
-## Who to Pair With
-- `copywriter` — for listing copy strategy
-- `growth-hacker` — for launch burst strategy (ratings velocity)
-- `conversion-optimizer` — for screenshot A/B testing
-
----
-
-## Tools
-AppFollow · Sensor Tower · AppTweak · AppFigures · MobileAction · Apple Search Ads Intelligence