forgetrail 0.3.0

package/prompts/personal-beta-outreach.md

@@ -0,0 +1,195 @@
+# Personal Beta Outreach Playbook
+
+Generate a structured outreach plan for inviting personal contacts to try your product during beta. Produces audience buckets, classification rules, per-bucket message templates, promo/offer policy, and a writing quality checklist to avoid AI-written and mass-email tells.
+
+---
+
+## Context
+
+**Your app** is in beta (or approaching launch). You have a personal network spanning close friends, professional contacts, casual connections, and people who know people. You need to invite them to try the product and give feedback -- but a single generic message wastes the warmth of close relationships and feels presumptuous for distant ones.
+
+This prompt produces an **operational playbook** -- not product code.
+
+**Prerequisites:**
+
+- `docs/BRAND_AND_PRODUCT.md` exists (voice, positioning, audience)
+- `docs/BUSINESS_PLAN.md` exists (pricing, trial length, promo code capabilities)
+- `docs/MARKETING_LAUNCH.md` exists (launch channel strategy, messaging framework)
+
+---
+
+## Instructions
+
+Read the project's brand doc, business plan, and marketing launch doc to understand: the product's one-sentence value prop, the target audience, the trial/pricing model, the promo code system capabilities, and the brand voice.
+
+Then produce a playbook covering all sections below. **Generalize** the audience buckets and message architecture; **customize** the templates with [BRACKETED] product-specific details.
+
+---
+
+## 1. Audience Buckets
+
+Define **6 mutually exclusive primary buckets** (A--F). Buckets mix **relationship warmth** with one **context-first** category:
+
+| ID | Bucket | Who belongs here | Relationship signal |
+|----|--------|------------------|---------------------|
+| **A** | Inner circle | Close friends/family; high trust, low formality | You'd ask a blunt favor without a pitch |
+| **B** | Strong professional | People you know well through work, not necessarily socially | Real conversations and mutual help |
+| **C** | Warm acquaintance | Met more than once or had a real exchange | They'd recognize your name without checking |
+| **D** | Light / casual | Thin relationship; mostly weak ties | Little or no 1:1 history |
+| **E** | Alumni / former org | Shared employer, program, school, or cohort is a **genuine** hook you'd **lead with** or **center** | You'd anchor the message on that shared context -- warmth may range from strong to thin |
+| **F** | Connector | May introduce others even if they don't use the product themselves | Primary value is intros, not personal trial |
+
+### Tie-breaker rule
+
+If stuck between two buckets, choose the **cooler** one (shorter copy, softer CTA, more conservative offer). Classify on **how the message would land today**, not the person's title or fame.
+
+### E vs B/C (when shared context matters)
+
+Use **E** when the message would **start or hinge** on alumni/org/cohort. Use **B** or **C** when you'd lead with the **person** and mention org second. Use **A** for true inner circle (org is color only). Use **F** when intros are the main ask.
+
+### Edge cases
+
+Include classification shortcuts for:
+
+- **Weak professional** (title overlap, little real relationship) -- default **D**; promote to **C** only with a specific remembered moment; **E** if shared org/cohort is still the honest anchor for the outreach.
+- **Dormant strong professional** ("used to be B, years since contact") -- classify by **current** warmth, not historical closeness. Often **E** if a **named** org/era is the reconnect hook; **C** if warmth is primary; **D** if the old bond is generic in memory. The opener can honor history while keeping structure honest.
+- **Senior / time-poor** -- bucket unchanged; set a flag; shorter copy, one clear ask.
+- **Former manager / direct report** -- use real warmth + recency, not org-chart position. Avoid A-level casual unless you're actually friends.
+- **Might share code widely** -- bucket unchanged; tighten promo caps/expiry.
+- **Between C and D** -- if you'd feel silly citing a shared memory, you're D. If you have one true sentence, you're C.
+
+---
+
+## 2. Classification Workflow
+
+Per contact, record:
+
+1. Name and **channel** (email, text, LinkedIn DM, etc.)
+2. **Primary bucket** (A--F)
+3. **Last meaningful touch** (this month / this year / years ago)
+4. **Optional flags:** time-poor, privacy-sensitive, might share widely
+
+**Tracking columns:** `Name | Channel | Bucket | Last touch | Promo code | Date sent | Reply | Signed up | Notes`
+
+---
+
+## 3. Message Architecture
+
+### Shared spine (all buckets)
+
+Every message follows a five-part skeleton. Weight shifts by bucket -- A is shortest; C is often longest; **E** flexes with how warm the tie is.
+
+1. Short **personal opener** (one line) -- why them or recent context
+2. **One sentence** on what [APP_NAME] helps with (outcome-oriented, not feature-list)
+3. **Beta ask:** you'd value their **feedback**
+4. **Optional:** extended trial via **promo code**
+5. **Easy out** -- no pressure; invite questions
+
+### Tone by bucket
+
+| Bucket | Length | Tone | CTA strength |
+|--------|--------|------|----------------|
+| A | Shortest | Warm, direct; humor OK | Strong ("try it," "be brutal") |
+| B | Short--medium | Professional-warm | Strong on feedback; moderate on trial |
+| C | Medium | Polite; specific memory if real | Moderate |
+| D | Short | Respectful; low assumption of time | Soft ("if it's relevant") |
+| E | Short--medium (flex) | Lead with shared org/cohort; tone matches actual warmth | Moderate; cooler **E** can match **D**-soft |
+| F | Short | Gratitude; focus on intros | Very soft on personal trial |
+
+### Product in one sentence (vary per bucket)
+
+Write **4 variants** of a one-sentence product description. Use different ones across messages so recipients who compare notes don't see the same rehearsed pitch:
+
+- **Full value stack** -- what the product produces from a single input
+- **Short / text-friendly** -- casual, compressed
+- **Latent user angle** -- for people who haven't started yet ("makes starting take five minutes, not a weekend")
+- **Positioning angle** -- what it is and what it's not
+
+### Promo code snippets
+
+Write 3 formality levels: casual (A/B), standard (C/D/E -- match warmth for **E**), connector (F).
+
+---
+
+## 4. Writing Quality Checks (AI-Tell Avoidance)
+
+> 💡 **Lesson learned:** Personal outreach messages drafted by AI or assembled from templates carry consistent tells that recipients -- especially senior professionals -- recognize instantly. The following checklist was developed by writing templates, then auditing them for patterns that read as "generated" rather than "written by a person."
+
+**Before sending, scan every message for:**
+
+- **Sincerity adverbs** ("genuinely," "truly," "honestly") -- cut them. Real sincerity comes from the ask, not the adverb.
+- **"I wanted to reach out"** -- filler. The recipient already knows you're contacting them.
+- **Repeated flattery formula** -- if "people whose judgment I trust" appears across multiple messages, it's a visible template. Vary or cut.
+- **Identical value-stack list** -- don't paste the same comma-separated product summary into every message. Use the variant one-liners (section 3) to diversify.
+- **Three-part feedback request** ("what resonates, what feels off, anything you'd want to see") -- pick one or two. Three-item lists are an AI fingerprint.
+- **Brand-doc phrasing in personal messages** -- if a sentence could appear on a pitch deck, rewrite it to sound like something you'd say out loud.
+- **"I hope this finds you well"** -- the most parodied email opener in professional communication.
+- **Structural parallelism across buckets** -- if all messages follow the same paragraph order with the same transitions, the architecture shows. Move pieces around per contact.
+
+**Anti-pattern:** Using AI to draft all five bucket templates, then sending them unchanged with only the name swapped. The structural similarity is the tell, even when no single phrase is wrong.
+
+**Pattern:** Use the templates as raw material. Per contact, rearrange the skeleton, pick a different product one-liner, and write the opener from a real memory. The goal is that two recipients who compare messages see family resemblance, not identical twins.
+
+---
+
+## 5. Template Messages
+
+Write one template per bucket (A, B, C, D, E, F) with:
+
+- Recommended **channel** and **tone** note
+- **Subject line** (for email buckets)
+- Message body using `[BRACKETED]` placeholders (for **E**, include `[SHARED_ORG_OR_ERA]` and an opener that centers shared context)
+- Brief **"why it works"** annotation
+
+Also produce:
+
+- A **shorter text/WhatsApp variant** for A
+- A **forwardable blurb** (stripped of personal framing, suitable for a stranger)
+
+### Template guidance by bucket
+
+| Bucket | Key characteristics |
+|--------|-------------------|
+| **A** | No formality, strong feedback ask ("be brutal"), acknowledge they may not be the target user |
+| **B** | Name a time investment ("20 minutes"), specify what feedback you want, include a forward option as secondary CTA |
+| **C** | More product context (less shared background to lean on), clear easy-out, forward/intro as natural secondary ask |
+| **D** | Shortest, low assumption, forward is the real CTA, promo code optional |
+| **E** | Opener anchors shared employer/program/cohort; body flexes between B- and C-like; include warmer vs cooler **E** notes |
+| **F** | "About your network, not you personally," offer a walkthrough, make forwarding frictionless |
+
+---
+
+## 6. Offer Tiers (Promo Mapping)
+
+Map **one promo code per bucket** (or per bucket x month) so redemptions are trackable. For each bucket, decide:
+
+- **Trial extension** (extra days beyond standard)
+- **Discount** (if any) and duration
+- **Redemption cap** and **expiry** -- tighten for buckets where codes might spread (C, D, E)
+
+General principle: **most generous for A** (highest trust), **most conservative for D** (weakest tie). **E** usually tracks **B**/**C** economics depending on warmth. F gets standard or nothing -- the reward is the relationship.
+
+---
+
+## 7. Guardrails
+
+- **1:1 feel** -- especially for D, avoid blast tone
+- **Beta honesty** -- rough edges OK to mention for A/B; keep D more polished
+- **Founder alignment** -- if multiple people send, use the same bucket definitions and code map
+- **No internal jargon** -- outreach copy should not reference spec filenames, internal feature names, or engineering terminology
+
+---
+
+## 8. Channel Notes
+
+| Channel | Guidance |
+|---------|----------|
+| **Text / WhatsApp** | Under ~150 words. No subject line, no sign-off. Link on its own line for clean preview. |
+| **Email** | Subject line personal, not marketing ("Something we built" > "Introducing [APP_NAME]"). Plain text preferred. |
+| **LinkedIn DM** | ~300-char preview truncation. Hook in first two sentences. If not connected, send connection request first. |
+
+---
+
+## Output
+
+Produce a single markdown document containing all sections above, customized to [APP_NAME] with specific product details filled in. The document should be usable as an operational playbook -- something the founders can open alongside their contact list and start sending from.

package/prompts/pre-launch-audit.md

@@ -0,0 +1,148 @@
+# Pre-Launch Audit
+
+Run this audit against the codebase before any major launch or deploy milestone. The goal is to catch gaps that would embarrass the product, break for real users, cause data loss, or undermine trust. This is NOT about new features — it's about polish, robustness, and reliability of what exists.
+
+---
+
+## How to Use
+
+Give this prompt to an AI coding assistant with full codebase access and ask it to perform the audit, reporting findings as **BLOCKER / HIGH / MEDIUM / LOW** with specific file paths, line numbers, and one-line fix suggestions.
+
+```
+Perform a pre-launch audit of this codebase using the checklist in [path to this file].
+Report findings as BLOCKER / HIGH / MEDIUM / LOW with specific file paths, line numbers,
+and one-line fix suggestions. For each finding, include the checklist item number it relates to.
+```
+
+---
+
+## Audit Checklist
+
+### 1. Error Handling & Boundaries
+
+- [ ] Does a custom error page exist with branded 404 and 500 pages?
+- [ ] Does the server error handler export structured logging (not just console.error)?
+- [ ] Do API routes return meaningful error messages, or do some silently swallow failures?
+- [ ] Are there fire-and-forget async calls missing error handling?
+- [ ] What happens if the database is down when a user saves? Is work lost after an expensive operation (LLM call, file generation) succeeds?
+
+> 💡 **Lesson learned:** The most painful production bugs are silent data loss
+> after expensive operations. If an LLM call costs $0.05 and succeeds, but the DB save
+> fails silently, the user loses work AND you lose money. Always save-or-retry after
+> expensive operations.
+
+### 2. Security & Infrastructure
+
+- [ ] Is the app's origin/host set correctly for production (reverse proxy awareness)?
+- [ ] Is the real client IP being forwarded correctly for rate limiting (not just 127.0.0.1)?
+- [ ] Is the database admin UI restricted to authorized IPs in production?
+- [ ] Are source maps disabled in production builds?
+- [ ] Does CSRF origin checking work correctly behind the reverse proxy?
+- [ ] Are there any hardcoded secrets, tokens, or API keys in the codebase (not in `.env`)?
+- [ ] Are security headers present (CSP, HSTS, X-Frame-Options, etc.)?
+- [ ] Are rate limits configured? Are auth endpoints and expensive routes (LLM) stricter?
+
+### 3. Legal & Compliance
+
+- [ ] Do privacy policy and terms of service pages exist and render full content?
+- [ ] Is there a cookie consent banner if analytics set cookies?
+- [ ] Does analytics respect opt-out?
+- [ ] Are AI processing disclosures present in the privacy policy (if using LLMs on user data)?
+
+### 4. SEO & Social Sharing
+
+- [ ] Does the landing page have `<title>`, `<meta description>`, `og:title`, `og:description`, `og:image`, and `twitter:card` tags?
+- [ ] Does `static/` contain `favicon.ico`, `favicon.svg`, `apple-touch-icon.png`, and `site.webmanifest`?
+- [ ] Does `robots.txt` exist and allow indexing of public pages?
+- [ ] Does `robots.txt` include a `Sitemap:` directive pointing at `sitemap.xml`?
+- [ ] Does a `static/sitemap.xml` exist listing all public routes (landing, privacy, terms)?
+- [ ] Is there a `<link rel="canonical" href="...">` on the landing page?
+- [ ] Is there JSON-LD structured data (`SoftwareApplication`, `FAQPage`, or similar) in the landing page's `<head>`?
+- [ ] Are `<title>`, meta description, Open Graph, Twitter, and JSON-LD `description` driven from the **same content module** (or shared constants) as the visible hero and key sections — not a second copy of the pitch only in `<head>`?
+- [ ] Does **audience / ICP language** match between meta tags, schema, and on-page copy (same specificity — e.g. band + seniority — not a generic phrase in one place and a precise phrase in another)?
+- [ ] After landing copy changes, are in-app story surfaces (About panel, Help introduction, etc.) still aligned on hero framing, section titles, timing claims, and customer-facing feature names?
+- [ ] If you added or renamed a **primary nav hub** (new top-level section, major tab family), do landing, About, Help, and FAQ **groupings** still describe the product map users see when logged in?
+- [ ] If users download **bundled exports** (ZIP, Word, PDF) that include marketing links or “learn more” CTAs, does every URL resolve on the **public** site (no dead routes like `/pricing` if you haven’t shipped that page)?
+
+- [ ] If the app offers **CSV (or spreadsheet) export** and a symmetric **import**, do header columns and row cell order match so round-trip or re-import does not silently map fields into the wrong columns?
+> 💡 **Lesson learned:** Canonical URL, sitemap, and JSON-LD structured data are all low-effort, moderate-SEO-upside items that are easy to forget. A `SoftwareApplication` schema with pricing aggregate offer gives Google richer context for search results. Add all three during the landing page build, not as a follow-up.
+
+### 5. Billing & Payments (if applicable)
+
+- [ ] Does the payment webhook handle all critical events (checkout completed, subscription updated, subscription deleted, payment failed)?
+- [ ] What happens when a trial expires? Is the user gracefully downgraded or stuck?
+- [ ] Has the full payment flow been tested end-to-end in test mode (signup → trial → upgrade → hit limits → downgrade → cancel)?
+- [ ] Is the webhook signing secret set in `.env`?
+- [ ] After **cold load**, **resume from sleep**, and **fast navigation** during onboarding, do trial/plan banners and upgrade modals match **server** state (no spurious "trial ended" or expired UI while the account is still in trial)?
+
+> 💡 **Lesson learned:** Payment edge cases are embarrassment machines.
+> Test the full lifecycle, not just the happy path. What happens when a subscription
+> update webhook arrives before the checkout completion webhook? What happens when
+> a user's card is declined on renewal?
+
+### 6. Data Integrity & Resilience
+
+- [ ] Has a database backup restore been tested? Can you spin up against a pulled snapshot?
+- [ ] Are there retry mechanisms for critical saves (especially after expensive LLM calls)?
+- [ ] What happens with concurrent usage across multiple tabs? Do refetch patterns cause conflicts?
+- [ ] Are database query workarounds documented for known driver/ORM issues?
+
+> 💡 **Lesson learned:** PocketBase's default 5K text field limit silently
+> truncated LLM output with no error. Check ALL fields that receive LLM output against
+> your database's field size limits. One systematic audit prevented 5 production bugs.
+
+### 7. Authentication & Sessions
+
+- [ ] Are auth cookies set with `httpOnly`, `secure`, and `sameSite`?
+- [ ] Does logout clear all cookies (auth, delegation, impersonation)?
+- [ ] What happens if access is revoked mid-session (e.g., delegation removed)?
+- [ ] Does the forgot-password flow work? Is email sending configured?
+- [ ] Is there session invalidation on password change?
+- [ ] If the app sends **app-owned** transactional email (welcome, billing, security notices) via a provider API, are production credentials set and is the **sending domain** authenticated (SPF/DKIM/DMARC per provider)?
+
+### 8. Client UX & Mobile
+
+- [ ] Does the app load with proper skeletons/spinners, or does it flash empty states?
+- [ ] What happens if the initial data load fails? Is there a retry/refresh indication?
+- [ ] Does the layout work on mobile (especially complex layouts like Kanban boards, multi-column panels)?
+- [ ] Are all modals/panels keyboard-accessible with Escape to close?
+- [ ] Are file upload size limits communicated to users before they pick a file?
+
+### 8a. Accessibility (Landing Page)
+
+- [ ] Is there a skip-to-content link as the first focusable element?
+- [ ] Is there a `<main>` landmark wrapping the primary content?
+- [ ] Do all `<section>` elements have `aria-labelledby` or `aria-label`?
+- [ ] Does the primary `<nav>` have `aria-label="Main"`?
+- [ ] Do all password inputs have show/hide toggles with `aria-pressed` and `aria-controls`?
+- [ ] Are tooltips used only where they add information not already visible? (See DESIGN_SYSTEM.md > Tooltip Usage Guidelines)
+
+### 9. Caching
+
+- [ ] Do server-side caches avoid storing error results? (Check TTLs and error-bypass logic.)
+- [ ] Does client-side caching avoid persisting failures?
+- [ ] Are caches keyed per-user to prevent data leaking between accounts?
+
+### 10. Deployment Pipeline
+
+- [ ] Does the CI/CD pipeline build, transfer, install deps, and restart correctly?
+- [ ] Are deployment secrets (SSH keys, host IPs, tokens) set as CI/CD secrets?
+- [ ] Does the service file have correct environment and dependency settings?
+- [ ] Does the setup script install all required system dependencies?
+
+### 11. Content Quality
+
+- [ ] Spot-check 2–3 LLM-generated outputs for tone, accuracy, and format after the latest model/prompt changes.
+- [ ] Verify any template markers or placeholders are fully resolved in generated content.
+- [ ] Check that generated content sections don't repeat each other unnecessarily.
+
+---
+
+## Severity Guide
+
+| Severity    | Meaning                                                                                           |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| **BLOCKER** | Launch cannot proceed. Data loss, security vulnerability, or complete feature failure.            |
+| **HIGH**    | Should fix before launch. Embarrassing UX, broken flow, or unhandled error visible to users.      |
+| **MEDIUM**  | Fix soon after launch. Degraded experience, missing polish, or edge case that affects some users. |
+| **LOW**     | Improvement opportunity. Better error messages, tighter validation, or minor UX refinements.      |

package/prompts/product-feedback-to-spec.md

@@ -0,0 +1,76 @@
+# Product Feedback to Spec
+
+Turn raw user product feedback (notes, quotes, bullets, or a transcript) into a concise, implementation-ready spec. Use this when you have feedback from a user interview, support ticket, or internal review and need a structured document engineers and PM can act on.
+
+---
+
+## How to Use
+
+1. Paste this entire file (or from **Instructions** downward) into an AI assistant.
+2. Append the raw feedback under **Input**, or paste it after the prompt in the same message.
+3. Save the resulting spec under `specs/` (e.g. `specs/product-feedback-YYYY-MM-DD_<short-name>.md`) if you want it tracked in-repo. For a full Phase-4 delivery skeleton (data/API/UI, milestones, implementation summary), expand into ForgeTrail **`docs/SPEC_FEATURE_TEMPLATE.md`** (MCP: `getTemplate({ name: "SPEC_FEATURE_TEMPLATE" })`) instead of stopping at this short form.
+
+---
+
+## Instructions
+
+You are a product-minded engineer. The user will provide raw product feedback below.
+
+Your job is to produce a **concise implementation-ready spec**, not a summary essay.
+
+### Output structure (use these headings)
+
+1. **Source** — One line: who/when/context if given; otherwise `Unattributed`.
+2. **Problem statement** — What is broken, missing, or confusing? One tight paragraph.
+3. **User goal** — What the user is trying to accomplish in their own terms (1–3 sentences).
+4. **Scope**
+   - **In scope** — Bullets: what we should change or add.
+   - **Out of scope** — Bullets: what we explicitly won’t do in this iteration.
+5. **Proposed behavior** — Step-by-step or bullet “when user does X, system does Y.” Be specific enough to implement.
+6. **Acceptance criteria** — Numbered, testable checks (Given/When/Then or checkbox style).
+7. **Edge cases & risks** — Short list (empty states, permissions, performance, abuse, copy/legal if relevant).
+8. **Open questions** — Numbered questions for PM/design/engineering; mark **Blocking** where needed.
+9. **Suggested priority** — P0 / P1 / P2 with one-line rationale.
+
+### Rules
+
+- Prefer **decisions** over vague options; if the feedback is ambiguous, state assumptions in **Open questions** and still propose a default.
+- Separate **facts from the feedback** vs **your inference**; label inference when it matters.
+- If the feedback touches multiple features, split into **Spec A / Spec B** or **Primary / Follow-up**.
+- Keep the whole doc skimmable: short paragraphs, bullets, no filler.
+
+---
+
+## Multi-Source Feedback Analysis (brainstorm then bucket)
+
+_Use this when you have feedback from multiple users, interviews, or sources and need to identify patterns before writing individual specs. This is affinity mapping formalized as a repeatable process._
+
+**Step 1: Generate the observation inventory.** From all feedback sources (interview transcripts, support tickets, NPS comments, user testing notes, app store reviews), extract every distinct observation — a quote, a behavior, a complaint, a request, a confusion, a delight. One observation per line. Do not filter or interpret yet. Aim for 50-200 observations depending on the volume of source material.
+
+> 📝 **Example prompt:** "Here are transcripts from [N] user interviews about [product/feature]. Extract every distinct observation — things users said, did, struggled with, requested, praised, or got confused by. One observation per line. Include the source (User 1, User 2, etc.) for traceability. Do not summarize or group yet."
+
+**Step 2: Bucket against hypothesized themes.** Define 5-8 themes that represent your hypotheses about what users care about. These might be:
+
+- User goals (what they are trying to accomplish)
+- Pain points (what frustrates them)
+- Feature requests (what they explicitly ask for)
+- Mental model gaps (where their expectations diverge from the product's behavior)
+- Delights (what they value and don't want to lose)
+- Workflow context (what they do before and after using your product)
+
+Score each observation against the themes. An observation may land in multiple themes.
+
+**Step 3: Review for research signals.**
+
+- **Observations that land in 3+ themes** — these represent core user needs that cut across concerns; they often point to the most impactful product changes
+- **Themes with many observations** — these are validated concerns worth acting on
+- **Themes with few observations** — either you didn't ask about them (probe in the next round) or they are not real user priorities (deprioritize)
+- **Observations that don't fit any theme** — the most valuable output of this step. These are signals your hypotheses missed. Cluster the unfitted observations and ask: is there a theme here you didn't anticipate?
+
+**Step 4: Feed into specs.** Each theme with sufficient signal becomes a spec (use the output structure above). Themes with weak signal become hypotheses for the next research round. Cross-theme observations inform architectural decisions (they suggest interconnected features, not isolated fixes).
+
+---
+
+## Input
+
+[PASTE RAW FEEDBACK HERE]