conectese 0.1.14

package/_conectese/core/best-practices/whatsapp-broadcast.md

@@ -0,0 +1,107 @@
+---
+name: "WhatsApp Broadcast"
+platform: "whatsapp"
+content_type: "broadcast"
+description: "Broadcast messages optimized for open rates, replies, and conversational engagement without triggering spam flags"
+whenToUse: |
+  Creating agents that produce WhatsApp broadcast messages or conversational marketing content.
+constraints:
+  message_max_chars: 4096
+  status_duration: "24h"
+  broadcast_list_max: 256
+  media_types: "image, video, document, audio"
+  optimal_message_length: "300-500 chars"
+version: "1.0.0"
+---
+
+## Platform Rules
+
+- WhatsApp broadcast messages are delivered as individual chats, not group messages. Recipients do not see each other. This creates a 1-to-1 conversational dynamic that must be respected in tone and structure.
+- Recipients must have your number saved in their contacts to receive broadcast messages. Without this, the message is silently dropped. Always prompt new contacts to save your number during onboarding.
+- WhatsApp Business API enforces messaging tiers based on sender reputation. New accounts start at 1,000 unique recipients per 24 hours. Maintaining high quality scores (low blocks/reports) unlocks higher tiers up to unlimited sending.
+- Messages that receive high block or report rates will degrade your quality rating from Green to Yellow to Red, eventually resulting in account restrictions or bans.
+- Open rates on WhatsApp average 90-98%, far exceeding email. This makes frequency discipline critical — every message is seen, so every bad message damages trust.
+- Send during business hours in the recipient's time zone (9 AM - 8 PM). Avoid weekends and holidays unless your content is specifically time-sensitive.
+- Limit broadcast frequency to 2-4 messages per week maximum. More than one message per day triggers blocks and opt-outs at scale.
+- WhatsApp Status (24-hour stories) can complement broadcasts for less urgent updates without cluttering the chat.
+
+## Content Structure
+
+### Broadcast Message Flow
+
+1. **Greeting line** — Personalized opening using {{name}} variable. Keep it warm and conversational, not corporate.
+2. **Value hook** — One sentence explaining what this message delivers. The recipient must immediately understand why they should keep reading.
+3. **Body** — 2-4 short paragraphs delivering the core value: tip, offer, update, or exclusive content. Use line breaks between paragraphs. One idea per paragraph.
+4. **CTA** — Single, clear action: reply with a keyword, tap a link, or forward to a friend. Make the action effortless.
+5. **Signature** — Brief sign-off with sender name or brand. Reinforces the personal, 1-to-1 feel.
+
+### Message Types
+
+- **Value broadcasts**: Tips, insights, exclusive content. Build trust and keep opt-in rates high. Aim for 60-70% of all broadcasts to be value-driven.
+- **Promotional broadcasts**: Offers, launches, limited deals. Use sparingly (max 1-2 per week) and always lead with value before the pitch.
+- **Transactional updates**: Order confirmations, shipping, appointment reminders. Keep factual and concise.
+- **Engagement prompts**: Polls, quick questions, feedback requests. Drive replies to strengthen sender reputation.
+
+### Media Best Practices
+
+- Images should include a text caption explaining the visual. Never send an image without context.
+- Videos should be under 60 seconds for highest completion rates. Include a one-line summary above the video.
+- Documents (PDFs, catalogs) work best with a 2-3 sentence description of what the recipient will find inside and why it is worth opening.
+- Voice notes feel highly personal but should be reserved for warm audiences. Keep under 90 seconds.
+
+## Writing Guidelines
+
+- **Write like you are texting a friend, not sending a press release.** WhatsApp is an intimate channel. Formal language feels invasive and out of place.
+- Keep messages under 500 characters when possible. Shorter messages get higher reply rates and feel less like spam.
+- Use 1-3 emojis per message to add warmth and visual breaks, but never more. Excessive emojis look unprofessional and spammy.
+- One message, one purpose. Do not combine a tip, a promotion, and a survey in a single broadcast. Split them into separate messages on separate days.
+- Use {{name}} personalization in the greeting. "Hi {{name}}!" converts significantly better than "Hi there!" or no greeting at all.
+- Structure CTAs as low-friction actions: "Reply YES to get the guide" or "Tap the link below" — not multi-step instructions.
+- Bold key phrases using WhatsApp formatting (*bold*, _italic_, ~strikethrough~) to create visual hierarchy in plain text.
+- Always include an opt-out option: "Reply STOP to unsubscribe." This is both a legal requirement in many jurisdictions and a trust signal.
+- Front-load the value. The first two lines appear in the notification preview. If they do not communicate value, the message goes unread.
+
+## Output Format
+
+```
+=== GREETING ===
+Hi {{name}}! [Warm, personalized opening — 1 line]
+
+=== BODY ===
+[Value hook — what this message delivers and why it matters. 1-2 sentences.]
+
+[Core content — tip, insight, offer, or update. 2-4 short paragraphs, one idea each. Use line breaks and *bold* for key phrases. Max 300-400 characters for this section.]
+
+=== CTA ===
+[Single clear action — reply with keyword, tap link, or forward. Must be effortless. 1-2 sentences max.]
+
+=== SIGNATURE ===
+[Sign-off with sender name or brand. 1 line.]
+
+[Opt-out line: "Reply STOP to unsubscribe."]
+```
+
+## Quality Criteria
+
+- [ ] Message opens with personalized greeting using {{name}} variable
+- [ ] Total message length is under 500 characters (excluding signature)
+- [ ] Value hook is clear within the first two lines (notification preview)
+- [ ] Body contains one purpose only: value, promotion, or engagement — never mixed
+- [ ] CTA is a single, low-friction action (reply, tap, or forward)
+- [ ] Emoji usage is 1-3 per message, adding warmth without clutter
+- [ ] WhatsApp formatting (*bold*, _italic_) is used for visual hierarchy
+- [ ] Opt-out instruction is included ("Reply STOP to unsubscribe")
+- [ ] Tone is conversational and 1-to-1, not corporate or broadcast-style
+- [ ] Message delivers standalone value even if the recipient ignores the CTA
+
+## Anti-Patterns
+
+- **Walls of text** — Messages exceeding 600-700 characters feel overwhelming on a mobile chat screen. Recipients block senders who consistently send long messages because they clutter the chat list.
+- **No opt-out option** — Failing to include an unsubscribe mechanism violates regulations in many jurisdictions (GDPR, TCPA) and erodes trust. Trapped users report instead of replying STOP.
+- **More than one message per day** — WhatsApp is a personal space. Daily broadcasts feel invasive and drive block rates above 5%, which degrades your sender quality rating and can lead to account restrictions.
+- **All-caps text** — SHOUTING IN CAPS feels aggressive in a conversational channel and triggers spam perception. It also reduces readability on small screens.
+- **Pure promotional without value** — Broadcasts that only sell without educating, entertaining, or informing train recipients to ignore or block you. Lead with value, sell second.
+- **Multiple CTAs in one message** — Asking the recipient to reply, click a link, visit your store, AND share with friends creates decision paralysis. One message, one action.
+- **No personalization** — Generic messages ("Dear Customer") signal mass messaging and feel impersonal in a channel designed for intimate communication.
+- **Sending without opt-in** — Adding contacts to broadcast lists without their explicit consent violates WhatsApp Business Policy and results in high report rates that destroy sender reputation.
+- **Attachments without context** — Sending images, PDFs, or videos without a text explanation wastes the recipient's data and attention. Always introduce what the attachment is and why it matters.

package/_conectese/core/best-practices/youtube-script.md

@@ -0,0 +1,122 @@
+---
+name: "YouTube Video Script"
+platform: "youtube"
+content_type: "script"
+description: "Long-form video scripts optimized for retention, CTR, and watch time with thumbnail-first planning"
+whenToUse: |
+  Creating agents that produce YouTube video scripts or long-form video content.
+constraints:
+  title_max_chars: 100
+  title_optimal_chars: "50-70"
+  description_max_chars: 5000
+  description_visible_lines: 2
+  thumbnail_size: "1280x720px"
+  optimal_duration: "8-15 minutes"
+  end_screen_duration: "5-20 seconds"
+version: "1.0.0"
+---
+
+## Platform Rules
+
+- **CTR + Watch Time** are the two most important metrics. A video needs both a compelling thumbnail/title (for clicks) AND strong retention (for algorithmic expansion).
+- The first 30 seconds determine whether viewers stay or leave. This is the make-or-break window for average view duration (AVD). Getting 70%+ AVD signals quality to the algorithm.
+- Thumbnail is 50% of a video's performance. A great video with a weak thumbnail will fail. Design the thumbnail before scripting.
+- Suggested videos are the primary traffic source for most channels. Optimize titles and thumbnails for browse and suggested placement. The algorithm tests with a small audience first, then expands based on CTR and AVD.
+- Session time is rewarded. Videos that lead viewers to watch more YouTube content get algorithmic favor.
+- Best upload days: Thursday, Friday, Saturday at 2-4 PM in your audience's time zone. Upload consistency matters — the algorithm rewards predictable schedules.
+- 8-15 minute videos hit the optimal balance: 8+ minutes enables mid-roll ads, under 15 minutes maintains strong retention.
+
+## Content Structure
+
+### Video Architecture
+
+1. **Hook (0-30 seconds)** — State the premise, show a preview of the payoff, create a curiosity loop that needs closing. "By the end of this video, you will know exactly how to..." Avoid asking for likes or subs here — the viewer has received no value yet.
+2. **Intro/Context (30 seconds - 1 minute)** — Brief background establishing why this topic matters. Keep it tight. No lengthy channel introductions or sponsor segments.
+3. **Body (1 minute - X minutes)** — Deliver the core content in 3-5 distinct sections. Use pattern interrupts every 30-60 seconds: B-roll, graphics, angle changes, story shifts, or on-screen text. Monotony causes retention drop-off.
+4. **Climax/Key Insight** — The most valuable moment, the "aha" realization. Place this at 60-70% through the video to reward viewers who stayed and pull the retention curve forward.
+5. **Summary (last 1-2 minutes)** — Recap the key points and reinforce the primary takeaway. This cements the value and primes the viewer for the CTA.
+6. **CTA + End Screen (last 20 seconds)** — One primary CTA (subscribe, watch the next video, or leave a comment). Use end screen elements: subscribe button and next video card. Do not stack 5 different asks.
+
+Use pattern interrupts every 30-60 seconds to reset viewer attention: cut to B-roll, zoom in/out, on-screen keyword highlight, story shift, angle changes, or audience questions.
+
+## Writing Guidelines
+
+- **Thumbnail first.** Design the thumbnail concept before scripting. If you cannot make a compelling thumbnail, reconsider the topic.
+- **Title formula**: [Curiosity gap] + [Specific benefit]. Example: "I Tried X for 30 Days — Here is What Happened." Front-load keywords in the first 50 characters.
+- **Hook must establish stakes in 30 seconds.** State the payoff, preview the value, create an open loop. No "hey guys, welcome back."
+- Write for spoken delivery. Short sentences, conversational language, natural speech patterns. If it sounds stiff read aloud, rewrite it.
+- Add timestamps/chapters in the description for navigation. First 2 lines of the description must contain the hook and primary keywords (only visible lines before "Show more").
+- Use 5-10 tags and 2-3 in-video cards linking to related content. Mark pattern interrupt cues (B-roll, graphics, angle changes) directly in the script.
+
+## Output Format
+
+```
+=== TITLE ===
+[Video title — 50-70 characters optimal, max 100. Curiosity gap + specific benefit. Front-load keywords.]
+=== THUMBNAIL CONCEPT ===
+[Visual description: subject/face expression, text overlay (3-4 words max), color scheme, composition. Must be readable at mobile thumbnail size.]
+
+=== HOOK (0-30s) ===
+[Spoken script for the first 30 seconds. State the premise, preview the payoff, create the curiosity loop.]
+[Visual cues]: [What appears on screen during the hook]
+
+=== INTRO (30s-1min) ===
+[Brief context — why this matters, who this is for. Keep under 30 seconds.]
+[Visual cues]: [Supporting visuals]
+
+=== BODY ===
+Section 1: [Subheading] (Timestamp: ~1:00-X:XX)
+[Script — spoken content] | [Pattern interrupts]: [B-roll, graphic cues] | [Key point]: [Takeaway]
+
+Section 2: [Subheading] (Timestamp: ~X:XX-X:XX)
+[Script — spoken content] | [Pattern interrupts]: [B-roll, graphic cues] | [Key point]: [Takeaway]
+
+Section 3: [Subheading] (Timestamp: ~X:XX-X:XX)
+[Script — spoken content] | [Pattern interrupts]: [B-roll, graphic cues] | [Key point]: [Takeaway]
+
+=== CLIMAX (at ~60-70% through) ===
+[The "aha" moment — most valuable insight or reveal] | [Visual cues]: [How to emphasize visually]
+
+=== SUMMARY (last 1-2 min) ===
+[Recap of key points. Reinforce the primary takeaway.]
+
+=== CTA + END SCREEN (last 20s) ===
+[One primary CTA] | [End screen elements]: [Subscribe button, next video card]
+
+=== DESCRIPTION ===
+[First 2 lines: Hook + primary keywords (visible before "Show more")]
+[Video summary — 2-3 sentences]
+TIMESTAMPS:
+0:00 - [Hook/Intro] | X:XX - [Section 1] | X:XX - [Section 2] | X:XX - [Section 3] | X:XX - [Summary/CTA]
+[Links: related videos, resources, social media]
+
+=== TAGS ===
+[5-10 relevant keyword tags, comma-separated]
+```
+
+## Quality Criteria
+
+- [ ] Thumbnail concept is defined before the script, with face/emotion, 3-4 word text overlay, and high contrast design
+- [ ] Title is 50-70 characters, front-loads keywords, and combines curiosity gap with specific benefit
+- [ ] Hook establishes stakes and creates an open loop within the first 30 seconds
+- [ ] Hook does not ask for likes/subs before delivering value
+- [ ] Script includes pattern interrupt cues every 30-60 seconds (B-roll, graphics, angle changes)
+- [ ] Body contains 3-5 distinct sections with clear subheadings
+- [ ] Climax/key insight is placed at 60-70% through the video
+- [ ] Total estimated duration is 8-15 minutes
+- [ ] Description includes timestamps for chapter navigation
+- [ ] First 2 lines of the description contain the hook and primary keywords
+- [ ] End screen uses the last 20 seconds with one primary CTA
+
+## Anti-Patterns
+
+- **Clickbait that does not deliver** — Misleading thumbnails and titles cause early drop-off, destroying average view duration and algorithmic trust. The video must fulfill the thumbnail's promise.
+- **Slow intros** — "Hey guys, welcome back to my channel, so today we are going to..." loses viewers immediately. Hook first, personal introduction later (or never).
+- **Asking for likes/subs in the first 30 seconds** — The viewer has received no value yet. Earn the ask by delivering value first, then requesting engagement.
+- **No timestamps** — Long videos without chapters frustrate viewers who want to navigate to specific sections, hurting retention and rewatch potential.
+- **Generic thumbnails** — Text-only or auto-generated thumbnails get dramatically lower CTR. Always design a custom thumbnail with face, emotion, and minimal text.
+- **No pattern interrupts** — Static talking-head without visual variety causes retention drop-off after 60 seconds. The audience's attention must be actively maintained.
+- **Too many CTAs** — "Like, subscribe, hit the bell, follow me on Instagram, check out my course, buy my merch..." dilutes every ask. Pick one primary CTA per video.
+- **Inconsistent upload schedule** — The algorithm and your audience both expect predictability. Erratic publishing kills momentum.
+- **Uploading without a custom thumbnail** — Auto-generated thumbnails are never acceptable. Always upload a designed thumbnail.
+- **Ignoring comments** — Creator replies boost comment visibility and signal community health. Unanswered comment sections look abandoned.

package/_conectese/core/best-practices/youtube-shorts.md

@@ -0,0 +1,112 @@
+---
+name: "YouTube Shorts"
+platform: "youtube"
+content_type: "shorts"
+description: "Short-form vertical video optimized for the Shorts feed, loop replays, and rapid audience growth"
+whenToUse: |
+  Creating agents that produce YouTube Shorts or short-form vertical video for YouTube.
+constraints:
+  max_duration_seconds: 60
+  aspect_ratio: "9:16 vertical"
+  hashtags: "3-5 max, include #Shorts"
+version: "1.0.0"
+---
+
+## Platform Rules
+
+- YouTube Shorts have a separate algorithm from long-form videos. Shorts views do not directly boost long-form distribution, and vice versa. Treat them as distinct content strategies.
+- The Shorts feed is swipe-based. Viewers decide to stay or swipe in the first 1-2 seconds. The hook window is even shorter than Reels or TikTok.
+- Completion rate and replays are the primary algorithmic signals. A Short that loops seamlessly and gets rewatched will be distributed far more widely than a longer Short with low completion.
+- Shorts can be posted any day of the week. The Shorts feed is less time-dependent than long-form uploads.
+- Including "#Shorts" in the title or description ensures proper categorization in the Shorts feed. Without it, the video may not surface in the dedicated Shorts experience.
+- Shorts work best for teasers, quick tips, behind-the-scenes content, and reaction/commentary clips. They serve as a top-of-funnel audience growth tool.
+- Frequency: 2-3 Shorts per week as supplements to long-form content is a sustainable cadence.
+- Hashtags are low-priority on YouTube compared to other platforms, but 3-5 relevant hashtags in the description help with initial categorization. The first 3 hashtags appear above the title.
+
+## Content Structure
+
+### Shorts Sequence
+
+1. **Hook (0-2 seconds)** — Text overlay or spoken hook that immediately creates curiosity. "Here is the trick nobody talks about..." or "Stop doing X, do this instead." The viewer is one swipe away from leaving. Make the first frame impossible to ignore.
+2. **Delivery (2-50 seconds)** — One point, one story, one tip. No fluff, no tangents, no filler. Get to the value immediately and deliver it concisely. Maintain visual variety with cuts, text overlays, and angle changes.
+3. **Punchline/Loop (last 5-10 seconds)** — The payoff that ideally loops back into the hook. Design the ending to visually or narratively connect to the beginning, creating a seamless loop that encourages replays.
+
+### Loop Design Techniques
+
+- End with a statement that leads directly into the opening hook. "And that is exactly why..." (cut to) "Here is the trick nobody talks about..."
+- Use visual match cuts: the last frame of the Short matches the first frame.
+- Pose a question at the end that the beginning of the Short answers.
+- Circular storytelling: end the story at the same point it began, with new context.
+
+## Writing Guidelines
+
+- **Hook must be instant.** The first 2 seconds determine everything. Use bold text overlays, a provocative opening statement, or a visually striking action. No title cards, no logos, no "hey guys."
+- Keep Shorts between 15-45 seconds for maximum completion rate. Shorter is generally better for the Shorts algorithm.
+- Add text overlays throughout the Short. Many viewers watch without sound. Key points, labels, and captions burned into the video are essential.
+- Write scripts at a fast, energetic pace. Shorts reward density. Cut all filler words: "um," "so," "basically," "you know."
+- Shoot natively in vertical 9:16. Never crop a horizontal video into vertical. Cropped content looks lazy, wastes screen space, and performs poorly.
+- One topic, one takeaway. A Short that tries to cover 3 points communicates none effectively. If you have multiple points, make multiple Shorts.
+- Include "#Shorts" in the title or description. Add 2-3 additional topic-relevant hashtags.
+- Title should be concise and curiosity-driven. It appears below the Short in browse and search.
+- Description should include #Shorts, relevant hashtags, and a brief context line.
+
+## Output Format
+
+```
+=== SHORTS SCRIPT ===
+
+HOOK (0-2s):
+[Visual]: [What appears on screen — action, scene, or text overlay]
+[Audio]: [Spoken hook or music cue]
+[Text Overlay]: [Bold on-screen text — max 8 words, large font]
+
+DELIVERY (2-50s):
+[Visual]: [Shot-by-shot breakdown — cuts every 3-5 seconds]
+[Script]: [Full spoken script for delivery. Fast pace, no filler.]
+[Text Overlays]: [Key points highlighted on screen at timestamps]
+
+PUNCHLINE/LOOP (last 5-10s):
+[Visual]: [Final shot — designed to connect back to the hook]
+[Script]: [Closing statement or reveal that loops into the opening]
+[Text Overlay]: [Punchline text on screen]
+
+=== TITLE ===
+[Short, curiosity-driven title — appears below the Short in browse]
+
+=== DESCRIPTION ===
+[Brief context line — 1 sentence]
+
+#Shorts #hashtag2 #hashtag3 #hashtag4
+[3-5 hashtags including #Shorts]
+
+=== LOOP NOTE ===
+[How the ending connects to the beginning for seamless replay]
+
+=== AUDIO NOTE ===
+[Original audio direction or trending sound suggestion]
+```
+
+## Quality Criteria
+
+- [ ] Hook delivers a clear curiosity gap or visual hook within the first 2 seconds
+- [ ] Total duration is 15-45 seconds for optimal completion rate
+- [ ] Content is one topic, one takeaway — no multi-point delivery
+- [ ] Text overlays are present throughout for sound-off viewing
+- [ ] Ending is designed for loop potential (visual or narrative connection to the start)
+- [ ] Video is natively vertical 9:16, not cropped from horizontal footage
+- [ ] "#Shorts" is included in the title or description
+- [ ] Script is tight with no filler words or unnecessary pauses
+- [ ] Title is concise and creates curiosity
+- [ ] Description includes 3-5 relevant hashtags
+
+## Anti-Patterns
+
+- **Horizontal Shorts** — Cropping a widescreen video into vertical 9:16 looks lazy and performs poorly. Always shoot natively vertical.
+- **Slow intros** — Any delay before the hook (logos, "welcome back," title cards) causes immediate swipe-away. The first frame must hook the viewer.
+- **No text overlays** — Many Shorts viewers watch without sound. A Short without burned-in text or captions loses a significant portion of its audience.
+- **Trying to cover too much** — A 60-second Short with 5 tips communicates none of them memorably. One point, delivered clearly, is always more effective.
+- **Missing #Shorts tag** — Without "#Shorts" in the title or description, the video may not surface in the dedicated Shorts feed, dramatically reducing its distribution.
+- **Repurposed horizontal video** — Simply re-uploading a clip from a long-form video without reframing for vertical is immediately obvious and signals low effort.
+- **No loop design** — Shorts that end abruptly without connecting back to the beginning miss the replay signal that drives algorithmic distribution.
+- **Ignoring comments** — Creator replies boost comment visibility and signal active community engagement. Unanswered Shorts comments reduce future distribution.
+- **Clickbait that does not deliver** — The payoff must match the hook's promise. Shorts viewers are ruthless with the swipe button when they feel misled.