forgetrail 0.3.0

package/prompts/black-hat-audit.md

@@ -0,0 +1,235 @@
+# Black Hat Security Audit Prompt
+
+Use this prompt with an AI coding assistant that has full access to a project workspace. Paste or feed it as-is. The assistant will perform a comprehensive manual code review and produce a structured security report.
+
+Save the output to `docs/BLACK_HAT_REPORT.md` using the template from `_forgetrail/docs/BLACK_HAT_REPORT.md`. After generating, triage all findings into `docs/TODO.md` with P0/P1/P2 priority.
+
+---
+
+## The Prompt
+
+```
+You are an expert penetration tester and application security engineer. Perform a comprehensive black hat security audit of this application. Assume the mindset of a motivated attacker with access to the source code (white-box). Your goal is to find every exploitable vulnerability, not just theoretical risks.
+
+Work systematically through the following audit areas. For each area, read the actual source code — do not guess or assume. Search for patterns, trace data flows from user input to dangerous sinks, and verify whether defenses exist.
+
+---
+
+### AREA 0: Fix efficacy — do existing defenses actually block?
+
+Run this area **first** on any codebase that has been audited before. The most dangerous finding is a defense everyone believes in that does not hold. Read the previous report (`docs/BLACK_HAT_REPORT.md`) and treat every "remediated" item as **unverified** until you prove it blocks.
+
+For each guard, sanitizer, escaper, or allowlist: **enumerate concrete bypass inputs and check them against the code line by line.** Where the project has a test runner, write a regression test with those inputs; a fix without a test that fails on the old code is not verified.
+
+Known failure modes to check by name:
+
+- **Exact match where a range is meant.** `host === '127.0.0.1'` leaves the rest of `127.0.0.0/8`; `=== '::1'` leaves `::ffff:127.0.0.1`. Compute ranges numerically instead of prefix-matching strings.
+- **Missing hostname normalization.** Trailing FQDN dot (`localhost.`, `metadata.google.internal.`), uppercase, IPv6 brackets, IPv4-mapped and NAT64-embedded IPv6 (`::ffff:7f00:1`, `64:ff9b::7f00:1`), decimal/hex/short IPv4 (`2130706433`, `0x7f000001`, `127.1`). Check what the platform's URL parser normalizes for you and what it leaves alone.
+- **Dead branches inside the guard.** A regex or condition that can never match the real input format (wrong number of leading colons, wrong case, checked before normalization). Prove each branch fires with a test input.
+- **Escape scheme mismatch.** Verify the escaping matches the **downstream parser**, not a familiar one from another system: SQL-style doubled quotes in a parser that uses backslash escapes will both fail to escape (trailing `\` eats the closing quote) and corrupt legitimate values. Compare against the vendor SDK's own escaping helper.
+- **Chained `.replace()` sanitization.** Sequential replaces re-scan their own output: an entity decoder that expands `&` before named entities still double-decodes. Prefer a single pass over the whole string, and iterate to a fixed point when stripping nested constructs.
+- **Guard exists but call sites skip it.** Grep for the raw sink (`fetch(`, `exec(`, `innerHTML`, raw filter interpolation) and diff that list against the guard's callers. Every unguarded call site is a finding, even when a helper is "the pattern."
+- **Validated value not the one used.** Check the URL/path/ID validated is the exact value passed to the sink (no re-parse, re-concat, or original-string fallback in between).
+- **Check-then-use gaps.** Redirect following, DNS re-resolution, and second reads after a check (TOCTOU). Note which are closed and which are only narrowed.
+
+Report each broken defense as a normal finding at the severity of the **underlying vulnerability it was supposed to close**, not as a documentation nit.
+
+---
+
+### AREA 1: Authentication & Session Management
+
+Read all auth-related routes (login, signup, logout, password reset, OAuth) and session/cookie handling code (middleware, hooks, interceptors).
+
+Check for:
+- Password policy: minimum length, complexity requirements, common password blocking
+- Login brute force protection: per-endpoint rate limiting (not just global), account lockout, exponential backoff
+- Session token security: httpOnly, secure, sameSite flags on all auth cookies
+- Session fixation: are sessions regenerated after login?
+- Session invalidation: are all sessions revoked on password change or logout?
+- Logout completeness: are all cookies and tokens properly cleared? Are clearing cookies set with correct flags?
+- OAuth state parameter: validated on callback? Cookies for state/verifier have proper flags?
+- User enumeration: do login vs. signup errors reveal whether an account exists? Timing side-channels?
+- Auth token refresh: is it happening too aggressively (DoS amplification)?
+- Cookie lifetime: are session cookies excessively long-lived?
+
+---
+
+### AREA 2: Authorization & Access Control (IDOR)
+
+Read EVERY API route/endpoint in the application. For each one, verify:
+
+- Is authentication checked? (reject unauthenticated requests)
+- Is ownership verified? (user can only access/modify their OWN records)
+- For admin-only routes: is admin/role status checked?
+- For delegation/impersonation systems: are delegates properly constrained? Can they access admin functions?
+- For multi-tenant systems: can tenant A access tenant B's data?
+
+Specifically look for the pattern where a route parameter (like an ID) is used to fetch/modify a record WITHOUT verifying the record belongs to the requesting user. This is IDOR — the most common and most dangerous access control flaw.
+
+Check:
+- Every GET endpoint: can users read other users' data by changing IDs?
+- Every PATCH/PUT endpoint: can users modify other users' records?
+- Every DELETE endpoint: can users delete other users' records?
+- List/search endpoints: are results filtered by the current user?
+- File download endpoints: is file ownership verified before serving?
+- Nested resources (e.g., /users/:id/files/:fileId): is the parent resource's ownership checked?
+
+---
+
+### AREA 3: Injection Attacks
+
+#### 3a. SQL / ORM / Database Query Injection
+- Search for raw query construction using string concatenation or template literals WITHOUT parameterization
+- Check if the ORM or query builder is used safely everywhere
+- Look for any raw SQL, raw MongoDB queries, or raw filter strings built from user input
+- If a custom sanitization function exists (like a tagged template for queries), verify it's used consistently — search for cases where it's NOT used
+
+#### 3b. XSS (Cross-Site Scripting)
+- Search for patterns where HTML is rendered without sanitization: dangerouslySetInnerHTML (React), {@html} (Svelte), v-html (Vue), [innerHTML] (Angular), raw HTML template insertion
+- For each instance: trace the data source. Is it user input, LLM output, scraped content, or database content?
+- Check if sanitization (DOMPurify, sanitize-html) is applied. Does it work on BOTH server-side rendering AND client-side?
+- Look for SSR-specific XSS: content sanitized client-side but rendered raw during server-side rendering
+
+#### 3c. Command Injection
+- Search for child_process, exec, spawn, system(), popen, subprocess, eval(), Function(), new Function
+- Check if any user input reaches these sinks
+
+#### 3d. LLM Prompt Injection (if applicable)
+- Check if user-supplied content is passed to LLM prompts
+- Look for prompt injection guards (system prompts, XML boundary tags, content wrapping)
+- Check if LLM output is rendered as HTML without sanitization (connects to XSS)
+
+---
+
+### AREA 4: SSRF (Server-Side Request Forgery)
+
+Search for any server-side code that makes HTTP requests based on user-supplied URLs:
+- URL scraping, link preview, webhook delivery, image proxying, file import from URL, RSS feed fetching
+
+For each instance, check:
+- Is the URL scheme restricted to http/https?
+- Are internal/private IP ranges blocked? (127.0.0.1, 10.x, 172.16-31.x, 192.168.x, 169.254.169.254, ::1, localhost, *.local, *.internal)
+- Does the code follow redirects? Can a redirect bounce to an internal host?
+- Is DNS rebinding considered?
+
+---
+
+### AREA 5: CSRF (Cross-Site Request Forgery)
+
+- How are state-changing requests protected? (CSRF tokens, Origin header checking, SameSite cookies)
+- Are there edge cases where protection is skipped? (missing Origin header, specific routes exempted)
+- Are webhook/callback endpoints properly exempted from CSRF but protected by signature verification instead?
+
+---
+
+### AREA 6: File Handling
+
+#### Upload:
+- File type validation (extension, MIME type, magic bytes)
+- File size limits
+- Path traversal prevention (can filenames contain ../ or absolute paths?)
+- Where are files stored? (local filesystem = dangerous, object storage = safer)
+- Are uploaded files served with proper Content-Type and Content-Disposition headers?
+
+#### Download/Export:
+- Zip slip: if ZIP files are created, are filenames sanitized to prevent path traversal?
+- Are file downloads gated by ownership checks?
+- Can exported data leak other users' information?
+
+---
+
+### AREA 7: Business Logic Vulnerabilities
+
+- Race conditions: look for non-atomic read-then-write patterns (TOCTOU). Common in: counters, usage limits, inventory, promo/coupon redemption, seat limits
+- Entitlement bypass: are paid features enforced server-side? Can a free user call paid API endpoints directly?
+- Promo/discount abuse: can codes be reused? Are max-redemption limits atomic? Can signup be raced to bypass per-user limits?
+- Payment/billing: are webhook signatures verified? Can subscription status be forged? Are success/cancel URLs controlled server-side?
+- Limit enforcement: if there are usage quotas, are they checked AND decremented atomically?
+
+---
+
+### AREA 8: Data Exposure
+
+- API responses: do they include sensitive fields that shouldn't be exposed? (password hashes, internal IDs, tokens, other users' data, full error stacks)
+- Error handling: do error responses include stack traces, library names, file paths, or SQL queries?
+- Logging: are secrets, tokens, or PII logged?
+- Source maps: are they enabled in production builds?
+- Environment variables: are any secrets exposed to the client via public env var prefixes (NEXT_PUBLIC_, VITE_, REACT_APP_)?
+
+---
+
+### AREA 9: Rate Limiting & DoS
+
+- Is rate limiting implemented? Per-IP? Per-user? Per-endpoint?
+- Are expensive operations (LLM calls, file processing, scraping) separately rate-limited?
+- Is the rate limiter in-memory (won't scale across instances) or shared (Redis)?
+- Can an attacker amplify requests? (e.g., one request triggers multiple downstream requests)
+- Are there unbounded loops, unlimited pagination, or missing timeouts?
+
+---
+
+### AREA 10: Secrets & Configuration
+
+- Search for hardcoded secrets, API keys, passwords in source code
+- Check if .env files are committed to version control (git ls-files .env)
+- Check .gitignore for proper exclusion of secret files
+- Review environment variable usage: are secrets only accessed server-side?
+- Check for default credentials in setup scripts or seed data
+
+---
+
+### AREA 11: Dependencies
+
+- Check package.json / requirements.txt / go.mod for known vulnerable packages
+- Note any unmaintained or deprecated dependencies
+- Check for overly permissive version ranges that could pull in compromised packages
+
+---
+
+## OUTPUT FORMAT
+
+Produce a structured markdown report with:
+
+### 1. Executive Summary
+- Total findings count by severity (CRITICAL / HIGH / MEDIUM / LOW / INFO)
+- 2-3 sentence summary of the most impactful issues
+- Overall security posture assessment
+
+### 2. Findings (grouped by severity)
+For each finding:
+- **ID**: Severity-prefixed sequential ID (C1, C2, H1, H2, M1, etc.)
+- **Title**: Concise description
+- **File**: Path and line numbers
+- **Impact**: What an attacker can achieve
+- **Code snippet**: The vulnerable code
+- **Attack scenario**: Step-by-step exploitation
+- **Fix**: Specific, actionable remediation with code example
+
+### 3. Positive Findings
+Table of what's done well — give credit for good security practices. This helps the developer understand which patterns to replicate.
+
+### 4. Remediation Priority
+Group fixes into:
+- **Immediate** (before launch / this week): anything directly exploitable
+- **Short-term** (next sprint): defense-in-depth, hardening
+- **Backlog**: nice-to-haves, future-proofing
+
+---
+
+## RULES
+
+- Read actual source code for every finding. Do not hallucinate file paths or code that doesn't exist.
+- Verify each finding. If a defense exists, note it. Don't report mitigated issues as vulnerabilities.
+- A defense counts as effective only when you can name the inputs it rejects. Prefer a regression test (one that fails against the pre-fix code) over prose; cite it in the report.
+- Never mark a prior finding remediated because a fix was committed. Re-read the current code and re-run the bypass inputs.
+- Include severity justification based on exploitability and impact, not just theoretical risk.
+```
+
+---
+
+## Usage Notes
+
+- For large codebases, consider running 2-3 subagents in parallel, each covering a subset of audit areas. This produces better coverage than a single pass.
+- After generating the report, use the `BLACK_HAT_REPORT.md` template to structure the output.
+- Triage findings into TODO.md immediately: P0 (Critical + exploitable High), P1 (defense-in-depth High + critical-path Medium), P2 (remaining Medium + Low + Info).
+- Re-run the audit after major feature additions or when preparing a new release.

package/prompts/brand-copy-edit-pass.md

@@ -0,0 +1,55 @@
+# Brand Copy Edit Pass
+
+A reusable prompt for making an editorial pass on brand, product, or marketing copy. Designed for docs like `BRAND_AND_PRODUCT.md` but applicable to any long-form brand or product narrative.
+
+---
+
+## The Prompt
+
+Review this file and make three sequential editing passes:
+
+### Pass 1: Resolve Annotations
+
+Look for any sections, phrases, or words marked with `[]` square brackets. Inside the brackets there may be comments in parentheses `()` explaining what needs to change. For each annotation:
+
+- Read the surrounding context to understand intent and tone
+- Propose and implement a replacement that addresses the comment
+- Match the voice and sophistication level of the surrounding prose
+- Remove the bracket markers entirely when done
+
+If a comment asks for a new paragraph or expanded content, write it in the same voice as the rest of the document. Do not add filler — every new sentence should carry weight.
+
+### Pass 2: Deduplicate
+
+Make a pass to identify repetition. Preserve all specifics, details, nuance, and clever phraseology — the goal is trimming redundancy, not flattening the writing.
+
+Look for:
+
+- The same argument made at full length in two different sections
+- Near-identical phrases reused within a few paragraphs of each other
+- Itemized lists that echo each other across sections
+- Closing lines that repeat the emotional beat of an earlier section
+
+For each instance, decide which location is the strongest home for the idea and trim or vary the other. Do not delete good lines — relocate or rephrase them if their current position is redundant.
+
+### Pass 3: Kill Filler Words
+
+Search for soft, unnecessary words that weaken the prose without adding meaning. Common offenders:
+
+- **"real"** (as in "the real work", "the real burden") — either drop or replace with something more specific
+- **"really"**, **"very"**, **"just"**, **"quite"**, **"actually"** — drop unless doing deliberate rhetorical work
+- **"helps"** — often too weak for what the product does; consider "equips", "enables", "delivers"
+- **"things"**, **"stuff"** — replace with the specific noun
+- **"in order to"** — replace with "to"
+- **"a number of"** — replace with the actual number or "several"
+
+For each filler word found: drop it if the sentence is stronger without it, or replace it with something that earns its place.
+
+---
+
+## Usage Notes
+
+- Run all three passes in sequence, not in parallel — Pass 2 depends on Pass 1's output, and Pass 3 benefits from the tighter text after Pass 2.
+- Show a summary table of changes after each pass so the author can review.
+- When in doubt about whether to cut, keep. The author's voice and specificity take priority over brevity.
+- This prompt works on any long-form brand doc, product narrative, or marketing page copy.

package/prompts/cialdini-marketing-audit.md

@@ -0,0 +1,141 @@
+# Cialdini Influence Audit for Landing Page & Marketing
+
+Audit your landing page, pricing section, and product touchpoints through the lens of Robert Cialdini's seven principles of influence (_Influence_ and _Pre-Suasion_). Produces a prioritized list of specific copy, UI, and structural changes that strengthen conversion without compromising brand authenticity.
+
+---
+
+## When to Run
+
+- Before spending on paid acquisition channels
+- After building your landing page but before launch
+- When conversion rates plateau and you need a structured diagnostic
+
+## Prerequisites
+
+Read these documents fully before beginning the audit:
+
+1. **BRAND_AND_PRODUCT.md** — voice, positioning, audience, what you're NOT
+2. **BUSINESS_PLAN.md** — pricing, target segment, growth channels
+3. **The landing page source code** — actual copy, layout, CTAs, pricing cards
+4. **Any existing social proof** — testimonials, user counts, press mentions
+
+## The Seven Principles — Audit Framework
+
+For each principle, assess:
+
+1. **Current state:** What's already in place (even partially)?
+2. **Gap severity:** Critical / Medium / Low / N/A
+3. **Prescriptions:** Specific, implementable changes with exact copy suggestions
+4. **Implementation priority:** Effort vs. impact ranking
+
+### 1. Social Proof
+
+> "People follow the lead of similar others."
+
+Check for: user counts, testimonials, logos, outcome data, case studies, activity indicators, success stories. Social proof is consistently the #1 conversion driver for SaaS landing pages.
+
+Prescriptions to consider:
+
+- **Aggregate proof counters** — "[N] [users] have [done X] this month." Even small numbers work if framed as curated.
+- **Outcome-framed testimonials** — Quote focused on the _experience_, not the tool. Include title level, not name.
+- **Peer specificity strip** — "Built for [Title A] · [Title B] · [Title C]." The titles are the proof that peers use this.
+- **Activity ticker** — Real-time anonymized activity. Only show when real data exists — never fabricate.
+
+### 2. Authority
+
+> "People defer to credible experts."
+
+Check for: domain expertise signals in copy, methodology framing, external validation (press, endorsements), builder credentials.
+
+Prescriptions to consider:
+
+- **Domain expertise in feature copy** — Name specific tools, platforms, or methods your audience recognizes. Generic descriptions like "analyzes your resume" are weaker than "shows how [specific platform] will parse your resume."
+- **Methodology authority** — Frame your approach as borrowed from established practice: "The [methodology] is standard practice at [credible entities]."
+- **Builder credibility** — If the founder has relevant credentials, a one-line note adds authority. Only if authentic.
+
+### 3. Scarcity
+
+> "People want more of what they can have less of."
+
+Check for: trial expiration framing, loss language, natural urgency signals. For professional audiences, manufactured urgency (countdown timers, limited slots) backfires badly.
+
+Prescriptions to consider:
+
+- **Loss-framed trial CTA** — Name what stops working after trial, don't just say "upgrade." "After [N] days, [specific features] lock — but everything you built stays."
+- **Bandwidth scarcity** (natural) — "Your [search/project/window] is finite. Every week without [your value prop] is a week of [concrete cost]."
+- **Opportunity cost anchor** — Professional service comparisons placed ABOVE the pricing grid, not below. Cialdini's contrast principle requires the expensive reference point before your price.
+
+**Do NOT do:** Fake countdown timers, limited-slot messaging, or "only X left" tactics for professional audiences.
+
+### 4. Reciprocity
+
+> "People feel obligated to return favors."
+
+Check for: free value before asking for commitment, trial generosity, useful content without paywall.
+
+Prescriptions to consider:
+
+- **Generous trial scope** — Full access during trial (not feature-limited). Give the best experience before asking for money.
+- **Free tools / content** — One genuinely useful feature or resource that works without signup.
+
+### 5. Commitment & Consistency
+
+> "People align with their prior commitments."
+
+Check for: progressive engagement, micro-commitments before the purchase decision, sunk-cost visibility.
+
+Prescriptions to consider:
+
+- **Progress visibility** — Show users what they've built during trial. "You've created N [items], customized M [things], and researched K [entities]."
+- **Friction-free trial start** — No credit card upfront. Each setup step is a micro-commitment that increases switching cost.
+
+### 6. Liking
+
+> "People prefer to say yes to those they like."
+
+Check for: brand personality, visual warmth, origin story, relatability.
+
+Prescriptions to consider:
+
+- **Origin story** — If authentic, a brief "why I built this" narrative builds parasocial connection.
+- **Visual warmth** — Warm color palettes, friendly (not clinical) UI feel. The design system itself is a liking signal.
+
+### 7. Unity
+
+> "People assent to those they see as 'one of us.'"
+
+Check for: shared identity signals, in-group language, community belonging.
+
+Prescriptions to consider:
+
+- **Identity language** — "[You're not an applicant, you're a [identity term]]." Status-elevating self-concept.
+- **Shared experience naming** — Reference specific frustrations your audience has. "You've been asked 'what's your current salary expectations?' three times this week."
+
+## Output Format
+
+For each principle, produce:
+
+```markdown
+### [Principle Name]
+
+**Current state:** [What exists]
+**Gap severity:** [Critical/Medium/Low]
+**Prescriptions:**
+| # | Tactic | Where | Copy / Detail | Priority |
+| --- | --- | --- | --- | --- |
+```
+
+Then a summary section:
+
+```markdown
+## Implementation Priority
+
+| Phase | Tactic IDs | Effort | Expected Impact |
+```
+
+## Constraints
+
+- **Honest over manipulative.** Every persuasion tactic must be grounded in truth. Never fabricate social proof, manufacture urgency, or claim credentials that don't exist.
+- **Audience-calibrated.** Professional audiences are skeptical. Tactics that work for consumer products (countdown timers, hype language) damage trust here.
+- **Brand-consistent.** All copy suggestions must match the established brand voice. Read BRAND_AND_PRODUCT.md before writing any copy.
+- **Actionable specificity.** Don't just say "add social proof." Say exactly what to add, where, and with what copy.

package/prompts/competitor-deep-dive.md

@@ -0,0 +1,201 @@
+# Competitor Deep Dive
+
+A reusable prompt for producing a structured competitive analysis document. Takes a competitor URL, researches their product thoroughly, compares it against your own positioning and features, and outputs a strategic comparison doc. Works for any product-to-product comparison where you have brand, business, and feature documentation.
+
+---
+
+## When to Run
+
+- When you discover a direct or adjacent competitor
+- Before major positioning or pricing decisions
+- When prospects ask "how are you different from X?"
+
+## Prerequisites
+
+Provide:
+
+1. **The competitor's URL** — the public website to research.
+2. **BRAND_AND_PRODUCT.md** — your product's voice, positioning, audience, and emotional framing.
+3. **BUSINESS_PLAN.md** — your product's pricing, growth strategy, and market positioning.
+4. **The product feature source** — the component, doc, or spec that lists all current features with descriptions.
+5. **USER_PITCH.md or equivalent** — the narrative framing used to describe your product to prospects.
+
+Read all internal docs fully before beginning competitor research.
+
+---
+
+## The Prompt
+
+You are a product strategist and competitive intelligence analyst. You are about to produce a deep-dive competitor comparison document.
+
+### Phase 1: Competitor Research
+
+Fetch and analyze the competitor's public-facing pages. At minimum:
+
+- **Homepage** — tagline, hero copy, value proposition, social proof claims, testimonial titles/industries
+- **Pricing page** — all tiers, prices, billing cadence, feature gating, free tier details
+- **Features page** (if separate) — full feature list with descriptions
+- **How-it-works flow** — what the user does vs. what the product does
+- **Footer links** — look for "For Business," "Partners," "Comparisons," "About Us" for additional positioning signals
+
+Extract and organize:
+
+| Data Point                 | What to Capture                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| **Tagline / hero claim**   | Exact text                                                                      |
+| **Core value proposition** | One-sentence summary of what they promise                                       |
+| **Target audience**        | Inferred from testimonials, copy, pricing, and use cases                        |
+| **Pricing**                | All tiers with prices and key limits — normalize to monthly for comparison      |
+| **Feature list**           | Every distinct feature with a one-line description                              |
+| **Social proof**           | User counts, press mentions, testimonial job titles                             |
+| **Philosophy**             | Implicit product philosophy (automation vs. strategy, volume vs. quality, etc.) |
+| **What they DON'T do**     | Gaps, missing categories, explicit disclaimers                                  |
+
+### Phase 2: Internal Product Catalog
+
+From the internal docs, build the equivalent catalog for your own product:
+
+- Target audience (titles, seniority, context)
+- Pricing tiers with limits and key differences
+- Complete feature list organized by category
+- Product philosophy and explicit non-goals
+- Current social proof assets (or lack thereof)
+
+This side of the comparison should be **factual and current** — based on what's shipped, not what's planned.
+
+### Phase 3: Positioning Comparison
+
+Write a side-by-side positioning table that captures the strategic differences:
+
+| Dimension            | Questions to Answer                                              |
+| -------------------- | ---------------------------------------------------------------- |
+| **Tagline**          | What does each product lead with?                                |
+| **Core promise**     | What outcome does each product sell?                             |
+| **Philosophy**       | Volume vs. quality? Automation vs. control? Speed vs. depth?     |
+| **Automation model** | What does the product do autonomously vs. what does the user do? |
+| **User's role**      | Passive (set-and-forget) vs. active (judgment-centric)?          |
+| **Input required**   | What does the user provide, and how often?                       |
+| **Output delivered** | What does the user get back?                                     |
+
+### Phase 4: Feature Matrix
+
+Build a detailed feature comparison organized by functional category. Adapt categories to the actual products being compared.
+
+For each feature:
+
+- ✅ = core feature, available on most/all plans
+- ⚡ = available but gated (higher tier only)
+- ❌ = not offered
+- Add a brief note where implementations differ meaningfully
+
+Don't inflate your product's capabilities or minimize the competitor's. Honest assessment builds trust with anyone reading this doc internally.
+
+### Phase 4b: Feature/Positioning Vocabulary Expansion (brainstorm then bucket)
+
+_Optional enrichment step. Run this after the feature matrix to discover comparison dimensions you missed._
+
+**Step 1: Generate a capabilities vocabulary.** From both products, the broader market, and adjacent categories, generate a flat list of 80-120 capabilities, claims, and positioning concepts — not just features, but also claims about outcomes, philosophies, and audience signals. Include capabilities neither product has but that buyers might expect.
+
+> Example: For a career tool comparison, this list would include not just "resume tailoring" and "ATS scoring" but also "employer branding signals," "salary benchmarking," "interview scheduling," "alumni network access," "executive presence coaching," "board placement" — capabilities that define the edges of the competitive space.
+
+**Step 2: Bucket against your differentiator categories.** Score each capability against your product's core differentiator dimensions (from BRAND_AND_PRODUCT.md "What Makes It Different" and the Phase 3 positioning comparison). For each capability, ask: which differentiator dimension(s) does this serve?
+
+**Step 3: Review for strategic signals.**
+
+- **Capabilities that land in multiple differentiator dimensions** — these are high-leverage features worth building or emphasizing
+- **Differentiator dimensions with very few capabilities** — either the dimension is thin (reconsider it) or there is genuine whitespace (opportunity)
+- **Capabilities that don't fit any dimension** — potential new competitive axes or features to explicitly declare out of scope
+- **Capabilities the competitor has that you bucketed into YOUR differentiator** — these threaten your positioning and deserve attention in the threat assessment
+
+**Step 4: Feed into Phases 5-7.** The enriched capability map makes the strengths analysis (Phase 5) and strategic implications (Phase 7) more complete. Capabilities you discovered in this step that neither product offers become roadmap candidates or explicit non-goals.
+
+### Phase 5: Competitive Strengths
+
+Two sections:
+
+#### Where the Competitor Wins
+
+List 5–8 genuine advantages the competitor has. For each:
+
+- State the advantage concretely
+- Note why it matters to their target audience
+- Assess whether it matters to YOUR target audience (it may not)
+
+#### Where You Win
+
+List 5–8 genuine advantages your product has. For each:
+
+- State the advantage concretely
+- Note why it matters to your target audience
+- Assess whether the competitor could close this gap easily (incremental improvement vs. architectural rebuild)
+
+### Phase 6: Threat Assessment
+
+#### Direct Competition Risk
+
+Rate as **High**, **Medium**, or **Low** with a one-paragraph justification. Consider:
+
+- Audience overlap (do you fight for the same users?)
+- Feature substitutability (could one replace the other?)
+- Price comparison (does the cheaper one cannibalize the expensive one?)
+- Switching costs (how easy is it to move between them?)
+
+#### Indirect Risks
+
+| Risk                     | Severity | Notes                                                  |
+| ------------------------ | -------- | ------------------------------------------------------ |
+| Category confusion       | ?        | Will prospects lump you together and compare on price? |
+| Feature creep from below | ?        | Could they incrementally add your differentiators?     |
+| SEO / discoverability    | ?        | Do they dominate your keyword space?                   |
+| Social proof gap         | ?        | Do they have stronger credibility signals?             |
+| Upstream platform risk   | ?        | Do they control a distribution channel you depend on?  |
+
+#### Non-Threats
+
+Explicitly list competitive scenarios that look scary on the surface but aren't real risks — and explain why. Prevents reactive decision-making.
+
+### Phase 7: Strategic Implications
+
+Organize recommendations into three buckets:
+
+#### Messaging
+
+- How to frame your product when prospects have seen the competitor
+- Language to use (and avoid) to prevent category confusion
+- Right comparison anchor for pricing (other tools? professional services? opportunity cost?)
+
+#### Product
+
+- Competitor features worth building — because they serve YOUR audience, not just because the competitor has them
+- Competitor features to explicitly NOT build — because they conflict with your positioning
+- Where to leapfrog instead of matching
+
+#### Go-to-Market
+
+- Search terms, content topics, and channels the competitive landscape suggests
+- How testimonials and social proof need to differ from the competitor's
+- Partnerships, integrations, or channels the competitor's model can't access
+
+## Constraints
+
+- **Accuracy over advocacy.** This is an internal strategic tool, not marketing copy. Be honest about where the competitor is stronger.
+- **Evidence-based claims.** Every claim about the competitor should trace back to their public pages. Every claim about your product should trace back to shipped code or published docs. Don't compare your roadmap to their current product.
+- **Audience awareness.** A feature critical for their audience may be irrelevant to yours. Always contextualize through the lens of who actually uses each product.
+- **No manufactured urgency.** If the competitive threat is low, say so. The most useful output is an accurate landscape read, not an argument for panic.
+
+## Output Format
+
+Save as `docs/COMPETITOR_[NAME].md` with:
+
+```
+# Competitor Analysis: [Competitor] vs. [Your Product]
+## Executive Summary (3–5 sentences)
+## Positioning at a Glance (table)
+## Target Audience (table)
+## Pricing Comparison (tables with analysis)
+## Feature Comparison Matrix (categorized tables)
+## Competitive Strengths (two sections: theirs and yours)
+## Threat Assessment (direct risk + indirect risks table + non-threats)
+## Strategic Implications (messaging, product, go-to-market)
+## Summary (2–3 sentence capstone)
+```