interface:
  display_name: "Suede Social"
  short_description: "Suede organic social strategy, content, and listening"
  default_prompt: "Use $suede-social on [target]. The user is planning social media strategy, content, or cadence for a brand or founder account. Work through platform strategy, content formats that travel, posting cadence, engagement, and listening, ground every recommendation in evidence the user can check, and return the decisions, the reasoning, and what to measure next."
policy:
  allow_implicit_invocation: true

{
  "skill_name": "suede-social",
  "evals": [
    {
      "id": 1,
      "prompt": "Help me create a LinkedIn content strategy. I'm a SaaS founder building in public and want to grow my personal brand to drive awareness for my product. I currently have 500 followers and post maybe once a week.",
      "expected_output": "Should check for product-marketing.md first. Should propose a manageable 3–5-pillar starting set for the founder, justified by audience coverage and production capacity. It should read current LinkedIn guidance and the account's last 30–90 days before naming a cadence, format, or time. If those data are unavailable, it should label 2–4 posts per week for four weeks as a starting hypothesis, rotate at least two formats and audience-local windows, and define the metrics that will decide the next cadence. It should provide hook options, a test calendar, a capacity-bounded engagement routine, and a batching plan without claiming carousels, stories, or more posting will automatically perform better.",
      "assertions": [
        "Checks for product-marketing.md",
        "Establishes 3-5 content pillars",
        "Applies LinkedIn platform guidance",
        "Provides hook formulas",
        "Creates weekly content calendar",
        "Includes a capacity-bounded engagement strategy",
        "Addresses batching strategy for consistency",
        "Labels cadence and format ranges as testable starting hypotheses"
      ],
      "files": []
    },
    {
      "id": 2,
      "prompt": "Write me a Twitter/X thread about the lessons I learned bootstrapping my SaaS to $10k MRR. Include hooks and a CTA at the end.",
      "expected_output": "Should verify that the claimed MRR and timeline are source-backed, then structure a coherent thread with an opening promise, evidence, lessons, and one CTA. It should choose the number of posts needed to deliver the proof without padding; when no account evidence exists, a 5–9-post draft is an explicit starting hypothesis with a compression option. It should reference the founder-journey pillar and include a relevant response prompt without claiming a universal platform best practice.",
      "assertions": [
        "Applies hook formulas from the skill",
        "Uses a story hook for the first tweet",
        "Structures thread with standalone but flowing tweets",
        "Uses specific numbers and stories",
        "Ends with clear CTA",
        "Uses an evidence-dependent thread length without padding",
        "Includes engagement prompts"
      ],
      "files": []
    },
    {
      "id": 3,
      "prompt": "i have a blog post that did really well. how do i turn it into social media content for multiple platforms?",
      "expected_output": "Should trigger on casual phrasing and apply the content repurposing system. It should treat platform formats, extraction count, link placement, and distribution timing as starting hypotheses to verify against current official guidance, account results, source richness, and approval capacity. It should adapt each candidate asset to its platform, return drafts for exact-content approval, and define what evidence will decide the next batch.",
      "assertions": [
        "Triggers on casual phrasing",
        "Applies content repurposing system",
        "Uses Blog Post → Social Content mapping",
        "Provides format for LinkedIn, Twitter/X, and Instagram",
        "Follows the repurposing workflow",
        "Extracts 3-5 key insights to repurpose",
        "Provides platform-specific format recommendations"
      ],
      "files": []
    },
    {
      "id": 4,
      "prompt": "My LinkedIn posts get like 200 impressions and almost no engagement. What am I doing wrong?",
      "expected_output": "Should request the account's recent reach, dwell or retention, replies, follows, format, timing, audience, and post samples before diagnosing. It should frame hooks, timing, formatting, topic fit, and participation as hypotheses, then propose a one-variable-at-a-time test across comparable posts. If account insights are unavailable, it should provide a manual worksheet and two bounded format and timing tests. It should provide before-and-after hook examples without promising higher reach.",
      "assertions": [
        "Applies analytics and optimization guidance",
        "Diagnoses potential engagement issues",
        "Addresses hook quality",
        "Addresses posting timing",
        "Recommends a measurable capacity-bounded participation test",
        "Suggests trying different content formats",
        "Provides specific before/after hook examples"
      ],
      "files": []
    },
    {
      "id": 5,
      "prompt": "Help me reverse-engineer what's working for top creators in the DevTools space on Twitter. I want to understand their content patterns.",
      "expected_output": "Should apply the reverse-engineering framework using a bounded sample of comparable DevTools accounts selected by audience, offer, account maturity, and available metrics. It should discover currently callable authorized collection tools and source terms; when none are available, it should provide a manual spreadsheet and work from user-supplied URLs or exports. It should add accounts and posts until another batch no longer changes the leading patterns rather than hard-code a sample size. It should analyze hooks, formats, CTAs, topics, timing, reach, and downstream actions only where the platform exposes them, then codify hypotheses and layer the user's voice.",
      "assertions": [
        "Applies the evidence-based content pattern framework",
        "Walks through the full process (find, collect, analyze, codify, apply)",
        "Builds a bounded comparable sample and stops at pattern saturation",
        "Describes what patterns to analyze",
        "Emphasizes layering authentic voice",
        "Provides data collection guidance"
      ],
      "files": []
    },
    {
      "id": 6,
      "prompt": "Write me a 5-email welcome sequence for new email subscribers who came from my LinkedIn audience.",
      "expected_output": "Should recognize this is an email sequence task, not social content. Should defer to or cross-reference `suede-emails`, which handles welcome sequences, drip campaigns, and lifecycle emails. May note the social-to-email bridge context but should make clear that `suede-emails` is the right skill for writing email sequences.",
      "assertions": [
        "Recognizes this as email sequence work",
        "References or defers to suede-emails",
        "Does not use Suede Social content patterns to write an email sequence",
        "May note social-to-email bridge context"
      ],
      "files": []
    },
    {
      "id": 7,
      "prompt": "I want to turn our new pricing guide into a LinkedIn carousel. It has 9 negotiation tactics for SaaS buyers. Help me structure the slides.",
      "expected_output": "Should load references/carousel-frameworks.md and pick a framework before writing slides. A list of nine named tactics can map to Hack List or Value-Stack, but the choice must be justified. It should produce a slide-by-slide structure with an exact-count cover, one named tactic per slide, a synthesis, and one CTA. It should verify current LinkedIn document-post requirements before specifying upload behavior. Any promised count must be delivered and every claim must be sourced. It should define success from the campaign objective using the current metrics available, such as completion, saves, qualified replies, profile visits, or follows, rather than declaring one metric universally superior.",
      "assertions": [
        "Loads or applies the carousel-frameworks reference",
        "Selects an appropriate framework (Hack List or Value-Stack) with a stated reason before drafting slides",
        "Slide 1 is written as a standalone scroll-stopper with the count or contrarian claim",
        "One tactic/idea per slide, each named",
        "Final slide has a synthesis and exactly one CTA",
        "Applies LinkedIn document-post guidance (PDF, post text as its own hook)",
        "Does not invent stats or pad the tactic count"
      ],
      "files": []
    }
  ]
}

# Carousel Frameworks

Five slide-by-slide narrative hypotheses for carousel tests. Verify current
composer limits, supported formats, account evidence, and production capacity
before choosing a structure, canvas, or slide count.

A carousel is not a blog post chopped into squares. It's a swipe-through with two jobs per slide: deliver one idea, and make the next swipe irresistible. These frameworks encode structures that show up repeatedly in high-performing carousels; treat them as starting structures to adapt, not rigid formulas — and expect to validate against your own analytics.

## Picking a Framework

| Your content is... | Use | Why |
|---|---|---|
| A list of resources, tools, or tips | **A: Value-Stack** | Completeness is the promise; the count is the hook |
| A personal result with a system behind it | **B: Problem-Proof** | Proof opens and closes the loop; the system is the meat |
| Several named techniques on one theme | **C: Hack List** | Each hack re-earns the swipe independently |
| A strong opinion about a common practice | **D: Rant Callout** | Conviction is the content; structure keeps it fair |
| A product or workflow you can show | **E: Demo Walkthrough** | Seeing the steps is more persuasive than describing them |

Two cross-framework starting hypotheses:

- **Slide 1 is the thumbnail.** It competes in the feed alone, before anyone knows a carousel follows. Design and write it as a standalone scroll-stopper.
- **One visual template per carousel.** Same layout, type scale, and palette on every interior slide. Variety between slides reads as clutter; consistency lets the *content* change while the frame stays still.

---

## Framework A: Value-Stack (starting range: 4–14 slides)

The "everything you need" carousel. Works because the cover makes a completeness claim — an exact count and an exact deliverable — and every swipe pays it down.

| Slide | Job | Pattern |
|---|---|---|
| 1 — Cover | State the exact count + exact deliverable. Specificity proves scale upfront. | "[N] [resource type] for [role/outcome]" |
| 2 to N−1 — Value delivery | One item or category per slide, 3–6 concrete sub-items each. Same visual template, zero filler slides. | "[Category/item] — [sub-items]" |
| N — Close | Convert the swipe-through into an action. | "[Action] for [the payoff]" — comment a keyword, follow, link in bio |

**Why the exact count matters:** a specific count is a checkable promise. Use it
only when the source list contains exactly that many substantive items; never
claim it universally outperforms a qualitative cover.

*SaaS example:* "12 ChatGPT prompts for SaaS onboarding emails" → one prompt per slide with the use case → "Comment PROMPTS and I'll send the full doc."

**Failure mode:** filler slides to hit a bigger number. Cut to the real count and
compare completion and qualified actions with the account baseline.

---

## Framework B: Problem-Proof (starting range: 6–10 slides)

The "I did X, here's the system" carousel. The hook is a *result stated as fact*, not advice — and the final slide shows the receipt, closing the loop slide 1 opened.

| Slide | Job | Pattern |
|---|---|---|
| 1 — Hook | A specific personal claim with a number. A result, not a tip. | "[I/we did X]. [Specific result, with number]." |
| 2 — Reframe the problem | Name what's *actually* going wrong so the reader recognizes themselves. | "The real problem — [named issue]" |
| 3–4 — The mechanism | Show the real system: named tools, named steps. Concrete beats vague. | "The system — [named tools/steps]" |
| 5 to N−1 — The detail | The literal prompt text, template, or step-by-step. This is the save-worthy part. | "[The literal prompt or process detail]" |
| N — Proof | The actual output artifact. A screenshot, not a description. | "[Screenshot of output] — the receipt" |

**The open loop is the engine:** slide 1 makes a claim, the last slide proves it, and everything between explains how. Readers swipe to see whether the receipt is real.

*SaaS example:* "We changed one onboarding email; here is the verified
before-and-after retention result." → the real problem → the sequence structure
→ the literal email copy → the sourced retention chart. Include a percentage
only when current product data supports it.

**Failure mode:** vague mechanism slides ("optimize your workflow") — if the middle slides don't name tools and steps, the proof slide reads as luck, not system.

---

## Framework C: Hack List (starting range: 6–10 slides)

The "numbered techniques" carousel. A contrarian cover creates status anxiety — most people are doing this wrong — and each numbered hack independently re-earns the swipe.

| Slide | Job | Pattern |
|---|---|---|
| 1 — Contrarian hook | A stat or claim implying most people fail at this. | "[Stat implying most people fail at X]" |
| 2 — The problem | Why the common approach fails, ideally with an analogy. | "The problem — [why it fails]" |
| 3 to N−1 — Numbered hacks | One named technique per slide. Bad-vs-good contrast makes each hack land instantly. | "Hack #[n] — [named technique]" |
| N — Synthesis + close | A one-line thesis tying the hacks together, then a save/share/follow CTA. | "[Thesis tying hacks together]" + [CTA] |

**Name every technique.** "The 3-second rule" is shareable and memorable; "keep it short" is neither. Named techniques travel — people repeat them and credit the source.

*SaaS example:* "Our trial-email baseline shows the opening problem." → show
the sourced baseline → Hack #1 → Hack #2 → a conclusion and CTA. Do not invent
an industry-wide percentage.

**Failure mode:** hacks that are restatements of each other. Each slide must survive alone — if two hacks collapse into one idea, merge them and go shorter.

---

## Framework D: Rant Callout (starting range: 4–8 slides)

The "someone had to say it" carousel. Personality-led and polarizing by design — the structure exists to keep the heat *fair* so it reads as conviction, not bitterness.

| Slide | Job | Pattern |
|---|---|---|
| 1 — Provocative claim | An unpopular opinion or direct accusation about a common practice. | "Unpopular opinion — [common practice]" |
| 2 to N−2 — Escalate the argument | Sensory, specific detail. Show the offense; don't gesture at it abstractly. Each slide raises the stakes. | "[Escalating, specific complaint]" |
| N−1 — Fairness pivot | "Don't get me wrong…" — clarify what you're *not* attacking. Anti-laziness, not anti-tool; anti-practice, not anti-person. | "The problem isn't [X], it's [Y]" |
| N — Close | Firm, personality-forward sign-off. Signed rants read as owned opinions; anonymous ones read as potshots. | "[Firm sign-off] — signed [name/persona]" |

**Fairness-pivot hypothesis:** test whether clarifying the target of the critique
improves comprehension and response quality. Do not claim it guarantees quotes
or prevents hostile comments.

*SaaS example:* "Your AI-generated LinkedIn posts are costing you customers." → the specifics (same em-dash cadence, same 'game-changer' vocabulary, zero lived detail) → "Don't get me wrong — I use AI daily. The problem isn't the tool, it's publishing the first draft." → "Write like you talk. — [Name]"

**Failure modes:** skipping the pivot (reads unhinged, invites pile-ons), or ranting about something your own product/content visibly does (the comments will find it).

---

## Framework E: Demo Walkthrough (starting range: 5–11 slides)

The "watch it work" carousel for product or workflow content. Show the finished result first, then the steps — the outcome earns attention for the process.

| Slide | Job | Pattern |
|---|---|---|
| 1 — Product + outcome | Brand/product plus the finished result. Lead with what they get. | "[Product] + [outcome], finished result" |
| 2 — Problem it solves | The specific frustration this replaces. | "[The specific pain this replaces]" |
| 3 — Process overview | The numbered step list, shown *before* the detail. Seeing the whole path lowers mid-swipe drop-off — readers commit when they know how long the road is. | "[N] steps to [outcome] in [timeframe]" |
| 4 to N−1 — Step-by-step | One real UI screenshot per step with a short caption. Real screenshots; mockups read as vaporware. | "Step [n] — [screenshot] — [caption]" |
| N — Result + positioning | The full-size output plus one brand-philosophy line. | "[Final output] + [positioning line]" |

**Overview-before-detail hypothesis:** test whether previewing the path improves
slide-level completion and comprehension for the current account.

*SaaS example:* "From CSV to live dashboard in 4 steps" → the pain (weekly manual reporting) → the 4-step overview → one screenshot per step → the finished dashboard + "Built for marketers, not analysts."

**Failure mode:** screenshots with too much UI. Crop to the action, zoom the relevant control, annotate with one arrow — each screenshot should make sense at thumbnail size.

---

## Platform Notes

**Instagram:** verify current composer limits, supported canvas, thumbnail crop,
and search behavior. A 4:5 canvas is a starting candidate only when the current
placement supports it.

**LinkedIn document posts:** verify current file, page, canvas, and preview
behavior. Test exact-count and qualitative covers, text density, and post copy
against account evidence.

**TikTok photo mode:** verify current support and limits, then test a lower and
higher slide-count treatment instead of assuming a pacing preference.

## Production Checklist

- [ ] Slide 1 works as a standalone feed post (test: would it stop the scroll with no carousel behind it?)
- [ ] One idea per slide — if a slide needs two sentences of setup, split it
- [ ] Same visual template on every interior slide
- [ ] Any count promised on the cover is exactly delivered (no filler, no rounding)
- [ ] Claims and numbers are real and yours — no invented stats or borrowed screenshots
- [ ] Text passes a target-device legibility check at the verified canvas size
- [ ] Final slide has one CTA, not three
- [ ] Caption/post text written as its own hook, not a repeat of slide 1

## Measuring What Worked

Choose carousel metrics from the objective and currently available account data:
completion, saves, qualified replies, profile visits, follows, or downstream
actions may each matter. Where slide-level analytics exist, use drop-off as a
diagnostic signal, not proof of a single cause. Test the cover, framework, and
middle-slide clarity one variable at a time. Track performance by framework and
keep only patterns supported by the account's evidence; see
[reverse-engineering.md](reverse-engineering.md).

# Listening Sources — Template

Copy this file to `.agents/listening-sources.md` in your project (or
`.claude/listening-sources.md`) and fill in the brackets. Suede reads it when
running the [listening workflow](listening.md).

Delete sections you don't use. Keep this short and current — stale sources are worse than no sources.

---

## What We're Listening For

**Brand / product:** [Your product name]
**Category:** [e.g., "AI writing assistant", "Postgres GUI"]
**Goal:** [e.g., "find people switching from Notion", "engage with B2B SaaS founders 50-200 employees"]

## ICP (for scoring)

Used by the [scoring rubric](listening.md#scoring-rubric) to judge ICP fit.

- **Role:** [e.g., "founder, head of marketing, marketing ops lead"]
- **Company stage:** [e.g., "seed to Series B SaaS, 10-200 employees"]
- **Industry:** [e.g., "B2B SaaS, infra, devtools"]
- **Signals they're a fit:** [e.g., "writes about GTM, runs paid ads, recently raised"]

---

## Target Accounts

Use these accounts as a review pool. Bound each run by current source volume,
relevance, risk, and human review capacity. Draft only the highest-priority
responses; never engage automatically or treat the whole list as a quota.

### LinkedIn (authorized browser or manual review)
- [Name] — `linkedin.com/in/handle`
- [Name] — `linkedin.com/in/handle`

### X / Twitter (browser-driven)
- [@handle]
- [@handle]

### Reddit
- u/[username]
- u/[username]

### Bluesky
- [handle.bsky.social]

### Blogs / Newsletters (RSS)
- [Name] — `https://example.com/feed/`
- [Name] — `https://example.substack.com/feed`

### YouTube channels (RSS)
- [Name] — channel ID `UCxxxxxxxx`

---

## Keywords (intent signals)

Search only the platforms currently authorized and reachable. When no connector
or browser is available, use the [daily-loop](listening.md#the-daily-triage-loop)
manual query and user-supplied URL workflow.

### High-intent (someone shopping or switching)
- `"alternative to [competitor]"`
- `"looking for a [category] tool"`
- `"recommend a [category]"`
- `"switching from [competitor]"`
- `"frustrated with [competitor]"`

### Problem signals (someone in pain)
- `"[category] is so [bad/hard/expensive]"`
- `"why is [category] [problem]"`
- `"hate [pain point]"`

### Brand mentions
- `"[your brand]"`
- `"[your brand misspelling]"`
- `"[your domain]"`

### Competitor mentions (monitor for switching language)
- `"[competitor 1]"`
- `"[competitor 2]"`

---

## Subreddits

Review through a currently authorized API, browser, or manual user export.

- r/SaaS
- r/Entrepreneur
- r/[your niche, e.g., "marketing", "devtools"]
- r/[adjacent community]

---

## Saved Searches (manual / browser-driven)

URLs for an authorized browser or manual user review.

### LinkedIn Sales Navigator
- [Search name] — `https://linkedin.com/sales/search/people?...`

### LinkedIn (regular)
- Posts hashtag — `https://linkedin.com/feed/hashtag/yourtopic/`

### X advanced search
- [Search name] — `https://x.com/search?q=...&f=live`

---

## Do Not Engage

Save yourself the regret.

- Accounts known for bad-faith dunking: [@handle], [@handle]
- Blocked brands / competitors who'll screenshot: [list]
- Topics to avoid: [politics, [your founder's hot takes], etc.]

---

## Notes for the Suede agent

- When asked for a ranked set, bound the output to current source volume and
  review capacity using the format in
  [listening.md](listening.md#the-daily-triage-loop)
- For LinkedIn and X, first discover a callable authorized browser and confirm
  visible identity; otherwise use the manual URL, screenshot, or export fallback.
- For other sources, use a currently callable authorized reader or the manual
  recipes in [listening.md](listening.md#sources--light-tooling-curl-recipes).
- Ask for a lookback that matches source volume and decision urgency; if the
  user delegates, start with 24 hours and label it a starting hypothesis.
- Always ask before posting — output drafts, user approves and posts manually

# Social Listening & Engagement Triage

How to surface posts that may merit an engagement draft. The goal is a short,
scorable list bounded by the user's review capacity, not a mandatory daily
count or an instruction to engage.

## Contents
- When to use this
- The daily triage loop
- Scoring rubric
- Comment quality tiers
- Sources & light tooling (curl recipes)
- Per-platform notes
- Common workflows

---

## When to Use This

Use listening when the goal is **commenting and relationships**, not posting. Typical asks:
- "Give me a ranked set of posts that may merit comment drafts"
- "Who's complaining about [competitor] right now?"
- "Find people asking for a tool like mine"
- "Surface recent posts from my approved target-account set"
- "What's the conversation around [topic] this week?"

If the user wants to **create** content, return to `suede-social`. Listening
feeds creation by surfacing angles, language, and objections, but the output is
different.

---

## The Daily Triage Loop

A repeatable triage loop sized to the user's selected lookback, source volume,
and review capacity.

1. **Pull** — fetch new posts from defined sources (target accounts, keywords, subreddits, hashtags). See [tooling](#sources--light-tooling-curl-recipes).
2. **Filter** — remove off-topic or stale items using a lookback justified by
   current platform velocity and the campaign goal.
3. **Score** — apply the [rubric](#scoring-rubric) and retain only the bounded
   review set the user can assess.
4. **Draft** — for each, draft a comment matched to the post's tier.
5. **Approval gate** — return drafts for review. Each comment is a separate
   external action and requires exact-content and identity approval before post.
6. **Log** — track what you commented on and what got replies. This is your engagement loop dataset.

Output format Suede should produce:

```
RANKED ENGAGEMENT DRAFTS — 2026-06-05

1. [Score 9/10] @author — LinkedIn — 2h ago
   "We just rolled out X and the team is loving it…"
   Why: ICP fit (B2B SaaS, 50–200 employees), buying-intent signal
   Suggested comment: [draft]
   Link: https://…
```

---

## Scoring Rubric

Score each post 1–10 across five dimensions, then sum and rank.

| Dimension | What it measures | Weight |
|-----------|------------------|--------|
| **ICP fit** | Is the author your target customer / influencer? | 2x |
| **Intent signal** | Are they expressing a problem, asking, or shopping? | 2x |
| **Reach potential** | Is the post getting traction (likes/comments rising)? | 1x |
| **Comment opportunity** | Can you say something genuinely useful, not generic? | 2x |
| **Recency** | Source falls inside the user-selected lookback and is still actionable | 1x |

**Intent signal examples (high-value):**
- "Looking for a tool that does X"
- "Why is [category] so painful?"
- "We just switched from [competitor] because…"
- "Anyone use [competitor] — is it worth it?"
- A complaint about a known competitor

**Drop if any of these are true:**
- Author isn't ICP and isn't an influencer
- The post is outside the justified lookback or current conversation volume
  makes a useful contribution unlikely; record the evidence rather than using a
  fixed age or comment-count cutoff
- Generic motivational/AI-slop post
- Self-promotion thread where a comment would not add relevant value
- You can't add anything beyond "Great post!"

---

## Comment Quality Tiers

Match the comment to the post. Don't waste a tier-1 draft on a tier-3 opportunity.

**Tier 1 — Relationship builder (target accounts, ICP, high intent)**
- Add a specific insight or counter-example
- Reference your own experience with specifics (numbers, names, outcomes)
- Ask a thoughtful follow-up that invites a reply
- Length: 2–4 sentences, no link

**Tier 2 — Visibility test (observed reach when visible, adjacent topic)**
- Add one sharp insight in one sentence
- Pattern: "Agreed — and the part most miss is [X]"
- Length: 1–2 sentences

**Tier 3 — Light touch (relationship maintenance)**
- Specific reaction, not "Love this"
- Quote a specific line and react to it
- Length: 1 sentence

**Never:** "Great post!", emoji-only, "+1", LinkedIn-isms like "This is gold 🔥"

---

## Sources & Light Tooling (curl recipes)

These example endpoints may change and can still impose terms or rate limits.
Verify current access and source terms before use. Prefer already callable
readers; otherwise give the user a manual source checklist.

The shell examples use `jq` and, for RSS, `xmllint`. First check whether they are
already installed. If not, use a manual/RSS-reader fallback or request explicit
installation approval after confirming the current platform and package source.
Do not run these installation examples without that approval:
```bash
# macOS
brew install jq
# xmllint ships with macOS; on Linux: apt install libxml2-utils
```

### Reddit (free, scriptable)

**New posts in a subreddit:**
```bash
curl -s -A "listening/1.0" \
  "https://www.reddit.com/r/SaaS/new.json?limit=25" \
  | jq '.data.children[].data | {title, author, url: ("https://reddit.com"+.permalink), score, num_comments, created_utc, selftext: (.selftext | .[0:300])}'
```

**Search across Reddit by keyword (last day, sorted new):**
```bash
curl -s -A "listening/1.0" \
  "https://www.reddit.com/search.json?q=KEYWORD&sort=new&t=day&limit=25" \
  | jq '.data.children[].data | {subreddit, title, url: ("https://reddit.com"+.permalink), author, score, created_utc}'
```

Swap `KEYWORD` for things like `"alternative to notion"`, `"recommend a crm"`, your competitor names, or your own brand for mentions. Use quotes around multi-word phrases.

### Hacker News (Algolia search)

**Recent stories mentioning a keyword (last 24h):**
```bash
SINCE=$(($(date +%s) - 86400))
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=story&numericFilters=created_at_i>${SINCE}" \
  | jq '.hits[] | {title, url, author, points, num_comments, created_at, story_id: .objectID, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
```

**Recent comments mentioning a keyword:**
```bash
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=comment&numericFilters=created_at_i>${SINCE}" \
  | jq '.hits[] | {author, comment_text, story_title, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
```

### Bluesky (free, public API)

**Search posts by keyword:**
```bash
curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=KEYWORD&limit=25&sort=latest" \
  | jq '.posts[] | {author: .author.handle, text: .record.text, likes: .likeCount, replies: .replyCount, url: ("https://bsky.app/profile/"+.author.handle+"/post/"+(.uri | split("/") | last))}'
```

### RSS for blogs, podcasts, YouTube channels

For target accounts that publish to RSS (most blogs, all YouTube channels):
```bash
# YouTube channel feed (replace CHANNEL_ID)
curl -s "https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID"

# Generic blog feed
curl -s "https://example.com/feed/" | xmllint --xpath "//item[position()<6]" - 2>/dev/null
```

### LinkedIn & X — discover access, then review

First discover whether an authorized browser or source-reading connector is
currently callable. Confirm the signed-in identity, user authorization, and
platform terms before opening an authenticated surface.

**Authorized-tool workflow:**
1. Confirm the visible account identity and exact research scope.
2. Open a bounded set of target URLs.
3. Read only the public or user-authorized content needed for the rubric.
4. Record source URL, timestamp, and any missing metrics.
5. Draft comments for review; never post or engage automatically.

**Manual fallback:** if no authorized browser is available, give the user the
URL checklist below and a worksheet, then work from links, screenshots, copied
post text, or exports they provide. Do not claim the feed was reviewed.

**Useful URL patterns to verify before use:**

| URL pattern | What it shows |
|-------------|---------------|
| `linkedin.com/in/HANDLE/recent-activity/all/` | A target account's recent posts |
| `linkedin.com/feed/hashtag/TOPIC/` | Hashtag feed |
| `linkedin.com/feed/` | Signed-in feed when the user authorizes access |
| `x.com/HANDLE` | A target account's profile |
| `x.com/search?q=QUERY&f=live` | Real-time search (use `f=live` for chronological) |
| `x.com/i/lists/LIST_ID` | A user-curated target-account list |

**Starting hypotheses:**
- A user-curated list may reduce irrelevant posts; compare it with keyword
  search and record which produces more rubric-qualified candidates.
- A target account's recent-activity surface may be easier to audit than a
  mixed feed; verify the URL still works and record gaps.
- Load only enough posts to cover the chosen lookback and sample. Stop at the
  authorization or platform limit; do not automate infinite scrolling.

**Possible account-owned alternatives, only if the user already has access:**

| Platform | Tools |
|----------|-------|
| LinkedIn | Sales Navigator (saved searches), Taplio (engagement) |
| X | TweetDeck/X Pro (saved columns), Typefully, Taplio, Tweet Hunter |

If a platform does not expose an authorized research path, use its native saved
searches manually or ask for a user export. Do not route around access controls.

---

## Per-Platform Notes

### LinkedIn
- Use the authorized-tool workflow or manual fallback above.
- Compare recent and older posts in the same account before assigning a recency
  score; do not assume a first-hour advantage.
- Judge draft comments on relevance, specificity, and conversation value, not a
  word-count or reach claim.
- Treat replies to other commenters as a relationship tactic to test, not a
  distribution guarantee.
- Tag the author in your reply only if it adds context

### Twitter/X
- Use the authorized-tool workflow or manual fallback above.
- Compare response windows using current account results; do not claim a
  universal first-30-minute advantage.
- Test quote posts, replies, and original commentary against the intended
  outcome rather than ranking them universally.
- Use a multi-post reply only when the content needs the space.
- Don't pile on dunks — relationships > clout

### Reddit
- Read the subreddit rules before commenting (some ban self-promotion outright)
- Earn karma in the sub before linking to anything you own
- Prefer specific answers that resolve the question; compare response quality
  rather than assuming length earns distribution.
- Never lead with your product — answer the question first

### Hacker News
- Comment quality bar is high; low-effort gets downvoted fast
- Founders commenting on threads about their product is welcomed if you're transparent
- Search past category discussions and verify that they are still current
  enough to answer.

### Bluesky
- Record volume and engagement-to-follower ratio where both are visible; do not
  assume either predicts fit.
- Tech and indie-hacker communities are active
- Compare custom feeds with topic search when both are available.

---

## Common Workflows

### "Give me a ranked set of posts that may merit comments"
1. Pull from the approved source set using a lookback justified by current
   platform velocity
2. Score with the [rubric](#scoring-rubric)
3. Output a review-capacity-bounded set with suggested comment drafts

### "Find people complaining about [competitor]"
1. Reddit search: `"competitor name" -site:competitor.com` sorted by new
2. HN comment search for competitor name
3. Bluesky search for competitor handle/name
4. Score by intent signal (high if switching language: "moving from", "alternatives to", "frustrated with")

### "Surface brand mentions from the last week"
1. Reddit search for brand name
2. HN search (stories + comments) for brand name
3. Bluesky search for brand name + handle
4. Output as: reply needed (yes/no), tone (positive/negative/neutral), suggested response

### "Find target-account posts I missed"
1. Maintain a list of target accounts with their RSS / Reddit usernames / Bluesky handles
2. Fetch each source's recent posts
3. Apply the justified lookback and output the bounded set sorted by score

---

## Setting Up the Source List

The user may maintain an approved source list at
`.agents/listening-sources.md` (or `.claude/listening-sources.md`). Suede reads
it when running the triage loop.

**A ready-to-fill template lives at [listening-sources-template.md](listening-sources-template.md).** Copy it into the project and edit. The source path depends on how the skill was installed:

```bash
# Plugin / marketplace install (most common):
cp .agents/skills/suede-social/references/listening-sources-template.md .agents/listening-sources.md
# .claude/ install:
cp .claude/skills/suede-social/references/listening-sources-template.md .agents/listening-sources.md
# Working inside the Suede creator skills repo:
cp skills/suede-social/references/listening-sources-template.md .agents/listening-sources.md
```

The template covers: brand/category, ICP (for scoring), target accounts per platform, intent keywords, subreddits, saved-search URLs, and a do-not-engage list.

# Suede Platform Limits Verification

Platform limits, composer previews, account entitlements, and recommendation
systems change. Do not treat remembered character, hashtag, attachment, or
truncation values as current. In every run:

1. Check current official platform documentation or the authenticated composer.
2. Record the account tier, surface, locale, and verification date.
3. Keep copy below the verified hard limit with room for links and disclosure.
4. Preview the actual truncation and attachment behavior before approval.
5. Treat hashtag count and placement as test variables, not algorithm facts.

If official documentation and an authorized composer are unavailable, return
the draft plus a manual preflight checklist. Do not invent a limit.

---

## Instagram

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Caption and hashtag limits | Verify official help or composer | None until verified |
| Hashtag count | Test against the account baseline | 0–3 relevant tags |
| Truncation | Preview on target surface | Put the core message first |

## Facebook

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Post and attachment limits | Verify official help or composer | None until verified |
| Hashtag count | Test against the page baseline | 0–2 relevant tags |
| Link preview | Preview on target surface | Add native context before the link |

## TikTok

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Caption, hashtag, and upload limits | Verify official help or composer | None until verified |
| Hashtag count | Test against the account baseline | 0–3 relevant tags |
| Truncation | Preview on target surface | Put the premise before metadata |

## LinkedIn

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Post, document, and attachment limits | Verify official help or composer | None until verified |
| Hashtag count | Test against the account baseline | 0–3 relevant tags |
| Truncation | Preview on target surface | Make the opening stand alone |

## Twitter/X

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Post, thread, and account-tier limits | Verify official help or composer | None until verified |
| Hashtag count | Test against the account baseline | 0–2 relevant tags |
| Truncation and cards | Preview on target surface | Keep the first post self-contained |

## YouTube

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Title, description, hashtag, and upload limits | Verify official help or Studio | None until verified |
| Hashtag count | Test against channel search and discovery data | 0–3 relevant tags |
| Truncation | Preview watch and search surfaces | Put the title promise first |

## Pinterest

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Pin, title, description, and hashtag limits | Verify official help or composer | None until verified |
| Hashtag count | Test against account search data | 0–3 only when relevant |
| Truncation | Preview on target surface | Use natural descriptive language |

## Threads

| Check | Current-Run Action | Starting Hypothesis |
|-------|--------------------|---------------------|
| Post, topic-tag, and attachment limits | Verify official help or composer | None until verified |
| Topic tags | Test only within verified limits | 0–1 relevant topic tag |
| Truncation | Preview on target surface | Put the premise in the opening lines |

---

## Evidence Rules

- A hard limit needs a current official source or authenticated composer
  readback.
- A recommendation needs current account or campaign evidence.
- A starting range must be labeled a hypothesis and compared with a baseline.
- Never claim fewer hashtags, a placement choice, or a platform feature
  improves reach without a controlled current-account comparison.

# Platform-Specific Strategy Guide

Use these as starting hypotheses, never platform truths. Before recommending a
cadence, time, format, or algorithm tactic, check current official guidance and
the account's last 30–90 days of reach, retention, saves, replies, follows, and
production capacity. Preserve the ranges below only as first-test bounds when
account evidence is unavailable.

## Contents
- LinkedIn
- Twitter/X
- Instagram
- TikTok
- Facebook

## LinkedIn

**Fit hypothesis:** B2B, professional expertise, networking, recruiting
**Audience hypothesis:** professionals and work-context communities
**Starting cadence hypothesis:** 2–4 posts per week for a four-week test
**Timing test:** compare two audience-local windows drawn from current follower
activity; if unavailable, rotate morning, midday, and evening slots

**Formats to test:**
- Personal stories with business lessons
- Contrarian takes on industry topics
- Behind-the-scenes of building a company
- Data and original insights
- Carousel posts (document format)
- Polls that spark discussion

**Risks to inspect:**
- Overly promotional content
- Generic motivational quotes
- Uncontextualized links that move readers away before delivering value
- Corporate speak without personality

**Format tips:**
- Test whether the opening line establishes useful context before any current
  truncation point; compare against the account baseline
- Use line breaks for readability
- Test a short and a long treatment of the same idea; use account-level dwell,
  completion, and response data to choose
- Test native context with body links, comment links, or no link where current
  platform guidance permits; compare qualified outcomes
- Tag people sparingly and genuinely

**Evidence to check:**
- Compare early and later response curves before setting reply windows.
- Compare comments, reactions, clicks, dwell, and follows at equal reach.
- Test text, document, link, and poll formats against the account baseline.
- Do not infer authority or algorithm preference from one high-reach post.

---

## Twitter/X

**Fit hypothesis:** real-time expertise, media, tech, and niche communities
**Audience hypothesis:** topic-led communities and professional peers
**Starting cadence hypothesis:** 3–5 original posts per week plus 3–5
substantive replies on each of 3–5 active days
**Timing test:** use current follower activity when available; otherwise rotate
three audience-local windows across comparable posts

**Formats to test:**
- Hot takes and opinions
- Threads that teach something
- Behind-the-scenes moments
- Engaging with others' content
- Memes and humor (if on-brand)
- Real-time commentary on events

**Risks to inspect:**
- Pure self-promotion
- Threads without a strong hook
- Ignoring replies and mentions
- Scheduling everything (no real-time presence)

**Format tips:**
- Test concise and expanded versions against equal-reach engagement and follow
  outcomes
- Threads: Hook in tweet 1, promise value, deliver
- Compare original commentary, quote posts, and replies using current results
- Use visuals to stop the scroll

**Evidence to check:**
- Compare replies, quote posts, threads, text, images, and video at equal reach.
- Measure profile visits, qualified replies, follows, and downstream actions.
- Test response timing rather than assuming a first-30-minute advantage.
- Do not infer paid-account distribution benefits without a controlled
  account-level comparison and current platform documentation.

---

## Instagram

**Fit hypothesis:** visual brands, creator narratives, commerce, lifestyle
**Audience hypothesis:** visual-first communities; verify account demographics
**Starting cadence hypothesis:** 2–4 feed posts per week plus Stories on 3–5
days per week
**Timing test:** compare two follower-active windows from current insights; if
unavailable, rotate midday and evening windows

**Formats to test:**
- High-quality visuals
- Behind-the-scenes Stories
- Reels (short-form video)
- Carousels with value
- User-generated content
- Interactive Stories (polls, questions)

**Risks to inspect:**
- Low-quality images
- Too much text in images
- Ignoring Stories and Reels
- Only promotional content

**Format tips:**
- Compare Reels, static posts, and carousels at equal account conditions.
- Test first-frame treatments against retention.
- Set carousel length from the idea and slide-level completion, not a fixed
  count.
- Test only the Story features that serve the current goal and are available on
  the authenticated account

**Evidence to check:**
- Compare format reach, retention, saves, shares, replies, and follows.
- Use Stories and interactive features only when they serve the audience goal.
- Treat consistency and format preference as account-level hypotheses.

---

## TikTok

**Fit hypothesis:** native short-form storytelling and discovery
**Audience hypothesis:** entertainment- and interest-led communities; verify
current account demographics
**Starting cadence hypothesis:** 3–5 posts per week for a four-week test
**Timing test:** compare follower-active windows when available; otherwise
rotate morning, midday, and evening slots

**Formats to test:**
- Native, unpolished content
- Trending sounds and formats
- Educational content in entertaining wrapper
- POV and day-in-the-life content
- Responding to comments with videos
- Duets and stitches

**Risks to inspect:**
- Overly produced content
- Ignoring trends
- Hard selling
- Repurposed horizontal video

**Format tips:**
- Test opening treatments in the first 1–3 seconds against retention.
- Start with two length bands that fit the idea, then use completion and
  downstream action to choose.
- Verify current upload requirements and composer previews; test 9:16 when it
  fits the placement, but do not reject another supported ratio without evidence
- Test native audio, original audio, and no-audio versions when rights and
  account context permit.
- Keep the test cadence stable enough to compare cohorts; do not claim it
  trains the algorithm.

---

## Facebook

**Fit hypothesis:** communities, local businesses, events, and groups
**Audience hypothesis:** community-oriented users; verify page or group insights
**Starting cadence hypothesis:** 2–4 posts per week plus community replies as
needed
**Timing test:** compare two audience-local windows from current insights; if
unavailable, rotate midday and early-evening slots

**Formats to test:**
- Facebook Groups (community)
- Native video
- Live video
- Local content and events
- Discussion-prompting questions

**Risks to inspect:**
- Link-only posts that provide no native context or discussion value
- Pure promotional content
- Ignoring comments
- Cross-posting from other platforms without adaptation

# Post Format Templates

Ready-to-use templates for different platforms and content types.

## Contents
- LinkedIn Post Templates (The Story Post, The Contrarian Take, The List Post, The How-To)
- Twitter/X Thread Templates (The Tutorial Thread, The Story Thread, The Breakdown Thread)
- Instagram Templates (The Carousel Hook, The Reel Script)
- Hook Formulas (Curiosity Hooks, Story Hooks, Value Hooks, Contrarian Hooks, Social Proof Hooks)

## LinkedIn Post Templates

### The Story Post
```
[Hook: Unexpected outcome or lesson]

[Set the scene: When/where this happened]

[The challenge you faced]

[What you tried / what happened]

[The turning point]

[The result]

[The lesson for readers]

[Question to prompt engagement]
```

### The Contrarian Take
```
[Unpopular opinion stated boldly]

Here's why:

[Reason 1]
[Reason 2]
[Reason 3]

[What you recommend instead]

[Invite discussion: "Am I wrong?"]
```

### The List Post
```
[X things I learned about [topic] after [credibility builder]:

1. [Point] — [Brief explanation]

2. [Point] — [Brief explanation]

3. [Point] — [Brief explanation]

[Wrap-up insight]

Which resonates most with you?
```

### The How-To
```
How to [achieve outcome] in [timeframe]:

Step 1: [Action]
↳ [Why this matters]

Step 2: [Action]
↳ [Key detail]

Step 3: [Action]
↳ [Common mistake to avoid]

[Result you can expect]

[CTA or question]
```

---

## Twitter/X Thread Templates

### The Tutorial Thread
```
Tweet 1: [Hook + promise of value]

"Here's exactly how to [outcome] (step-by-step):"

Tweet 2-7: [One step per tweet with details]

Final tweet: [Summary + CTA]

"If this was helpful, follow me for more on [topic]"
```

### The Story Thread
```
Tweet 1: [Intriguing hook]

"[Time] ago, [unexpected thing happened]. Here's the full story:"

Tweet 2-6: [Story beats, building tension]

Tweet 7: [Resolution and lesson]

Final tweet: [Takeaway + engagement ask]
```

### The Breakdown Thread
```
Tweet 1: [Company/person] just [did thing].

Here's why it's genius (and what you can learn):

Tweet 2-6: [Analysis points]

Tweet 7: [Your key takeaway]

"[Related insight + follow CTA]"
```

---

## Instagram Templates

### The Carousel Hook
```
[Slide 1: Bold statement or question]
[Slides 2-9: One point per slide, visual + text]
[Slide 10: Summary + CTA]

Caption: [Expand on the topic, add context, include CTA]
```

This is the generic shape. For five full slide-by-slide narrative architectures (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough) with selection guidance and per-slide copy slots, see [carousel-frameworks.md](carousel-frameworks.md).

### The Reel Script
```
Hook (0-2 sec): [Pattern interrupt or bold claim]
Setup (2-5 sec): [Context for the tip]
Value (5-25 sec): [The actual advice/content]
CTA (25-30 sec): [Follow, comment, share, link]
```

---

## Hook Formulas

The first line determines whether anyone reads the rest.

### Curiosity Hooks
- "I was wrong about [common belief]."
- "The real reason [outcome] happens isn't what you think."
- "[Impressive result] — and it only took [surprisingly short time]."
- "Nobody talks about [insider knowledge]."

### Story Hooks
- "Last week, [unexpected thing] happened."
- "I almost [big mistake/failure]."
- "3 years ago, I [past state]. Today, [current state]."
- "[Person] told me something I'll never forget."

### Value Hooks
- "How to [desirable outcome] (without [common pain]):"
- "[Number] [things] that [outcome]:"
- "The simplest way to [outcome]:"
- "Stop [common mistake]. Do this instead:"

### Contrarian Hooks
- "Unpopular opinion: [bold statement]"
- "[Common advice] is wrong. Here's why:"
- "I stopped [common practice] and [positive result]."
- "Everyone says [X]. The truth is [Y]."

### Social Proof Hooks
- "We [achieved result] in [timeframe]. Here's the full story:"
- "[Number] people asked me about [topic]. Here's my answer:"
- "[Authority figure] taught me [lesson]."

# Suede Content Pattern Analysis

Instead of guessing, analyze a lawful, recent sample of comparable content and
extract hypotheses to test on the user's account. A pattern in another account
is evidence for a test, not proof that it will transfer.

## Contents
- The 6-Step Framework (Comparable Set, Collect, Analyze, Playbook, Layer Voice, Convert)
- The Formula
- Reverse Engineering Checklist

## The 6-Step Framework

### 1. COMPARABLE SET — Find Relevant Accounts

Build a bounded set of accounts with similar audience, offer, maturity, and
format access. Start with enough accounts to represent more than one style, then
add another batch only while it changes the leading patterns.

**Selection criteria:**
- Enough recent posts for a within-account comparison
- Reach or engagement measures visible at a comparable grain
- Audience overlap with your target market
- Mix of established and rising creators

**Where to find them:**
- LinkedIn: Search by industry keywords, check "People also viewed"
- Twitter/X: Check who your target audience follows and engages with
- Use a currently callable authorized research tool, or manual search and
  user-supplied URLs
- Look at who gets featured in industry newsletters

### 2. COLLECT — Build a Lawful Bounded Sample

Before collection, discover the currently callable tools, verify authorization
and platform terms, and record which metrics are actually visible. Collect only
what the analysis needs. Stop when another bounded batch no longer changes the
leading patterns.

**Collection paths:**
- Platform-native export or analytics the user is authorized to access
- Authorized browser or source reader within platform terms
- Manual collection into a spreadsheet from user-supplied URLs
- No available access: provide the worksheet and ask the user for an export

Do not bypass access controls or bulk-scrape a platform that prohibits it.

**Data to collect:**
- Post text/content
- Engagement metrics (likes, comments, shares, saves)
- Post format (text-only, carousel, video, image)
- Posting time/day
- Hook/first line
- CTA used
- Topic/theme

### 3. ANALYZE — Extract What Actually Works

Sort and analyze the data to find patterns:

**Quantitative analysis:**
- Compare posts within the same account and metric availability
- Define higher- and lower-performing cohorts from the observed distribution
- Look for format patterns while controlling for reach and account size
- Treat day and time as hypotheses, not universal best windows
- Compare topic performance

**Qualitative analysis:**
- What hooks do top posts use?
- How long are high-performing posts?
- What emotional triggers appear?
- What formats repeat?
- What topics consistently perform?

**Questions to answer:**
- What's the average length of top posts?
- Which hook types recur in the observed higher-performing cohort?
- What CTAs drive most comments?
- What topics get saved/shared most?

### 4. PLAYBOOK — Codify Patterns

Document repeatable patterns you can use:

**Hook patterns to codify:**
```
Pattern: "I [unexpected action] and [surprising result]"
Example: "I stopped posting daily and my engagement doubled"
Why it works: Curiosity gap + contrarian

Pattern: "[Specific number] [things] that [outcome]:"
Example: "7 pricing mistakes that cost me $50K:"
Why it works: Specificity + loss aversion

Pattern: "[Controversial take]"
Example: "Cold outreach is dead."
Why it works: Pattern interrupt + invites debate
```

**Format patterns:**
- Carousel: Hook slide → Problem → Solution steps → CTA
- Thread: Hook → Promise → Deliver → Recap → CTA
- Story post: Hook → Setup → Conflict → Resolution → Lesson

**CTA patterns:**
- Question: "What would you add?"
- Agreement: "Agree or disagree?"
- Share: "Tag someone who needs this"
- Save: "Save this for later"

### 5. LAYER VOICE — Apply Direct Response Principles

Turn the strongest observed hypotheses into original tests with these voice
principles:

**"Smart friend who figured something out"**
- Write like you're texting advice to a friend
- Share discoveries, not lectures
- Use "I found that..." not "You should..."
- Be helpful, not preachy

**Specific > Vague**
```
❌ "I made good revenue"
✅ "I made $47,329"

❌ "It took a while"
✅ "It took 47 days"

❌ "A lot of people"
✅ "2,847 people"
```

**Short. Breathe. Land.**
- One idea per sentence
- Use line breaks liberally
- Let important points stand alone
- Create rhythm: short, short, longer explanation

```
❌ "I spent three years building my business the wrong way before I finally realized that the key to success was focusing on fewer things and doing them exceptionally well."

✅ "I built wrong for 3 years.

Then I figured it out.

Focus on less.
Do it exceptionally well.

Everything changed."
```

**Write from emotion**
- Start with how you felt, not what you did
- Use emotional words: frustrated, excited, terrified, obsessed
- Show vulnerability when authentic
- Connect the feeling to the lesson

```
❌ "Here's what I learned about pricing"

✅ "I was terrified to raise my prices.

My hands were shaking when I sent the email.

Here's what happened..."
```

### 6. CONVERT — Turn Attention into Action

Bridge from engagement to business results:

**Soft conversions:**
- Newsletter signups in bio/comments
- Free resource offers in follow-up comments
- DM triggers ("Comment X and I'll send you...")
- Profile visits → optimized profile with clear CTA

**Direct conversions:**
- Link placement tested against current platform guidance and comparable account
  results
- Contextual product mentions within valuable content
- Case study posts that naturally showcase your work
- "If you want help with this, DM me" (sparingly)

---

## The Formula

```
1. Find what's already working (don't guess)
2. Extract the patterns (hooks, formats, CTAs)
3. Layer your authentic voice on top
4. Test and iterate based on your own data
```

## Reverse Engineering Checklist

- [ ] Defined a bounded comparable-account set with inclusion reasons
- [ ] Collected only authorized fields and stopped at pattern saturation
- [ ] Ranked by engagement rate
- [ ] Documented a bounded set of recurring hook patterns, with sample size
- [ ] Documented top 5 format patterns
- [ ] Documented top 5 CTA patterns
- [ ] Created voice guidelines (specificity, brevity, emotion)
- [ ] Built template library from patterns
- [ ] Set up tracking for your own content performance

# Short-Form Video: Hooks, Scripts & Strategy

Detailed reference for creating short-form video content on TikTok, Instagram Reels, and YouTube Shorts.

---

## Video Hook Library

### Curiosity Hooks (engagement hypothesis)

**The "Secret" Formula:**
- "The secret to [outcome] that nobody talks about"
- "I found the overlooked feature in [product/platform] that changes everything"
- "I can't believe this actually works..."

**The Unexpected Discovery:**
- "I tried [thing] for 30 days and I was NOT expecting this"
- "This completely changed how I think about [topic]"
- "Nobody talks about this, but..."

**The Question:**
- "Why does nobody talk about this?"
- "Am I the only one who didn't know this?"
- "The reason [common thing] doesn't work is..."

### Value Hooks (save-intent hypothesis)

**The Promise:**
- "How to [achieve outcome] in [specific timeframe]"
- "[Number] [things] that will [benefit]"
- "Everything you need to know about [topic] in 60 seconds"

**The Hack/Shortcut:**
- "[Outcome] hack that actually works"
- "The [adjective] way to [outcome]"
- "If you're struggling with [problem], watch this"

**The Warning:**
- "Stop doing [common practice] — here's why"
- "[Number] mistakes that are killing your [results]"
- "Why [thing you think is good] is actually hurting you"

### Story Hooks (retention hypothesis)

**The Transformation:**
- "3 months ago, I [bad state]. Today, I [good state]."
- "Here's how I went from [before] to [after]"
- "I used to think [old belief]. Then [event] changed everything."

**The Failure:**
- "I made a huge mistake with [topic]"
- "Here's why I stopped [common practice]"
- "I lost [something significant] because of this mistake"

**The Journey:**
- "So this just happened..."
- "This changed everything for me"
- "Let me tell you about the time I [interesting situation]"

### Contrarian Hooks (response hypothesis)

- "Unpopular opinion: [bold statement]"
- "[Common advice] is actually wrong"
- "I'm going to get hate for this, but..."
- "Most [audience] get this completely wrong"

---

## Scripting Template

```markdown
## Video: [Working Title]

**Platform:** TikTok / Reels / Shorts
**Length:** XX seconds
**Format:** [Talking head / Slideshow / Demo / Screen recording]

### Hook (0-3 sec)
- Visual: [What viewer sees]
- Audio: [What they hear]
- Text overlay: [On-screen text]

### Body (3-X sec)
- [Timestamp] - [What happens/what you say]
- [Timestamp] - [Next beat]
- [Continue...]

### CTA (final 3-5 sec)
- Verbal: [What you say]
- Text: [On-screen text]
- Action: [Follow, comment, link in bio, etc.]

### Production Notes
- Music/sound: [Trending sound or music choice]
- B-roll needed: [List any clips needed]
- Graphics: [Any text animations or overlays]
```

---

## Video Structures

These five beat sheets are the full set. Pick one before scripting, then test
the opening against the account's comparable-format retention baseline.

### Problem-Solution (15-30 sec)

```
[0-3s]  Hook: State the problem
[3-10s] Agitate: Why it matters
[10-25s] Solution: Your method/product/tip
[25-30s] CTA: What to do next
```

Starting fit hypothesis: a single objection, a demo, a fix with visible proof

### List Format (30-60 sec)

```
[0-3s]  Hook: "X things that [outcome]"
[3-50s] Items: One every 5-8 seconds
[50-60s] CTA
```

Starting fit hypothesis: save-intent content, checklists, roundups

### Tutorial (30-60 sec)

```
[0-3s]  Hook: Show the end result first
[3-8s]  Overview: "Here's how..."
[8-50s] Steps: Quick, clear instructions
[50-60s] Result + CTA
```

Starting fit hypothesis: process reveals, software walkthroughs, how-tos

### The Story Arc (45-60 sec)

```
[0-3s]  Hook: Tease the outcome
[3-15s] Setup: Context and stakes
[15-45s] Journey: What happened
[45-55s] Resolution: The result
[55-60s] Lesson/CTA
```

Starting fit hypothesis: personal stories, case studies, testimonials

### The POV/Skit (15-30 sec)

```
[0-3s]  Setup: Text overlay sets the scene
[3-25s] Performance: Act out the relatable scenario
[25-30s] Punchline or twist
```

Starting fit hypothesis: relatable content, humor, niche communities

---

## Caption & Subtitle Spec

Use captions as an accessibility and comprehension default. Treat any watch-time
lift or sound-off viewing rate as account-specific: verify it with current
retention and audio metrics where the platform exposes them.

- **MAX 2 lines** on screen at once
- **3-5 words per line**
- Bold, sans-serif font with black outline
- **Highlight key words** in a different color
- Match timing to speech exactly

Caption tooling, export specs, and edit execution belong to `suede-video`.

---

## Visual Patterns

### Talking Head
- Good lighting (ring light or window light)
- Eye contact with camera
- Hand gestures for emphasis
- Interesting background (bookshelf, plants, studio setup)

### Slideshow/Carousel Video
- Test 2–4 seconds per slide as a starting range, then adjust from retention
- Text overlays with key points
- Consistent style/branding
- Voiceover or trending sound

### Screen Recording
- Zoom in on important areas
- Add cursor highlight or click animations
- Keep movements smooth and intentional
- Overlay your face in corner (optional but boosts engagement)

### B-Roll Heavy
- Show don't tell
- Test 1–3 seconds per shot as a starting range, then adjust from retention and
  comprehension
- Match cuts to voiceover beats
- Mix wide, medium, and close-up shots

---

## Audio Strategy

### When to Use Trending Sounds
- Entertainment/lifestyle content where the sound fits your message
- When the trend is still rising (check platform trending pages)
- Don't use when it distracts from your message or is already declining

### When to Use Original Audio
- Educational content where you're speaking
- Storytimes and personal narratives
- Product demos and tutorials
- Building a recognizable brand voice

### Voiceover Tips
- Speak slightly faster than normal conversation
- Vary your tone — avoid monotone delivery
- Pause for emphasis on key points
- Record in a quiet space, use noise removal
- AI voices work for faceless content (ElevenLabs, etc.)

### Music Selection
- Match energy to content (upbeat for tips, emotional for stories)
- Avoid copyrighted music on Reels/Shorts
- Use platform music libraries for safety
- Lower music volume under voiceover (ducking)

---

## Posting Strategy

### Timing hypotheses

Use current follower-activity data and official platform guidance when
available. If they are unavailable, rotate comparable posts through three
audience-local starting windows—morning (7–10), midday (11–14), and evening
(18–21)—for a bounded four-week test. These are test bins, not best times.

### Cadence hypotheses

| Goal | Starting Test | Decision Rule |
|------|---------------|---------------|
| Build a baseline | 3–5 posts per week for four weeks | Keep only if quality and production capacity hold |
| Maintain presence | 2–3 posts per week for four weeks | Compare reach and downstream actions with prior period |
| Test a format | 4–6 comparable posts across two weeks | Change one format variable and compare with account baseline |

Adjust the range to the account's current cadence, source volume, and review
capacity. More posts are not automatically better.

### Batch Creation Workflow

1. **Ideate** (30 min): Generate 10-20 concepts
2. **Script** (1 hour): Write scripts for 5-10 videos
3. **Batch film** (2 hours): Record all talking head content
4. **Edit** (2-3 hours): Edit and add captions
5. **Schedule** (planning estimate: 15–45 min): queue the approved timing-test
   cells and record the hypothesis

---

## Analytics & Iteration

### Metrics That Matter

| Metric | What It Tells You |
|--------|-------------------|
| Watch time % | Is content engaging throughout? |
| Completion rate | Did hook + content deliver? |
| Saves | Is content valuable enough to revisit? |
| Shares | Is content worth spreading? |
| Comments | Did content spark conversation? |
| Follows | Did viewer want more from you? |

### What to Test

1. **Hooks**: Same content, different opening
2. **Length**: 15 sec vs 30 sec vs 60 sec
3. **Format**: Talking head vs slideshow vs demo
4. **Time**: Morning vs afternoon vs evening
5. **CTA**: Different calls to action

### When to Pivot

- After a bounded cohort, if completion or retention is materially below the
  account's trailing comparable-format baseline, test a different opening.
- If reach is high but qualified follows or downstream actions are low, inspect
  CTA and audience fit.
- If saves and shares diverge, treat that as a format clue to investigate, not
  a universal content diagnosis.
- If comments are negative, classify the objections and safety risk; do not
  manufacture controversy for distribution.