# Gotchas Common failure modes for the social-content-engine skill. --- ## Gotcha: Rebuilding the calendar instead of extending it **Why it matters:** The calendar is the durable artifact — it is the reason this is a content operation and not a campaign generator. When each run starts from a blank calendar, the owner re-approves dates they already approved, and posts that were scheduled last month quietly get duplicated or dropped. ### ✗ Bad ``` Owner: "Give me another month of posts." → Build a fresh 30-day calendar from scratch. → Two rows collide with posts already scheduled in HubSpot. ``` ### ✓ Good ``` Open the existing calendar first, then report: Published since last run: 6 posts (Jun 2 – Jun 24) Still scheduled: 4 posts (through Jul 6) Gap starting: Jul 7 "I'll extend from Jul 7. Same cadence, three a week?" ``` --- ## Gotcha: Writing a caption before reading the voice profile **Why it matters:** Voice fidelity is the stated adoption barrier for this skill. Owners do not abandon it because the graphics are wrong; they abandon it because the caption sounds like a brand account and not like them. The shared profile exists so a correction made once holds across every skill. ### ✗ Bad Draft 12 captions in the owner's general industry register, present them, and rewrite all 12 after the owner says "this doesn't sound like me." ### ✓ Good Read `../../../shared/voice-profile.md` first. Anchor on the never-dos before each caption, not just the first. If no profile exists, build one from their own posts and confirm it before drafting at volume. --- ## Gotcha: Restating a Shopify price from memory **Why it matters:** A wrong price in a public post cannot be quietly fixed after a hundred people have seen it. Prices change between sessions, and the calendar is long-lived, so a number carried over from an earlier run is routinely stale. ### ✗ Bad "The mini-split was USD 2,400 last time we posted — I'll use that again." ### ✓ Good Read `variants[].price` fresh for every post that names a number. If the connector did not return one, say the price is unavailable and ask. Only claim "was X, now Y" when `compare_at_price` exists and is genuinely higher. --- ## Gotcha: Generating ANY Canva design for an email row **Why it matters:** Canva is out of scope for the email path entirely. Canva email-template autofill produces placeholder graphics (stock landscapes, blank rectangles) in service-grid tiles, and variation thumbnails fail to render in chat. Emails are text-only from this skill, period. Generating a Canva email design — even one — breaks that rule. ### ✗ Bad ``` Calendar has 6 social rows + 2 email rows. → Step 6 generates 6 social designs + 2 email designs. → Email designs ship with placeholder service tiles. ``` Or any variation: "I'll generate the email template just to give you a visual reference," "I found an email template that might work, want to preview it?", "Here's a Canva design for the Jun 5 email…" — all forbidden. ### ✓ Good ``` Step 2: Calendar built with Path column. - 6 rows tagged Canva (social) - 2 rows tagged Text-only (no Canva) Step 6: Generates exactly 6 Canva designs. Email rows are not passed to any Canva endpoint. Step 8: Drafts 6 social captions + 2 full emails (subject + preheader + body) as plain text. Step 9: Stages 6 social posts. Surfaces 2 emails inline for the owner to copy into their email tool. ``` If the owner explicitly asks for a Canva email design ("can you make me a Canva version of the Jun 5 email?"), redirect: "This skill keeps emails as text-only because the Canva email path produces placeholder graphics. If you want a Canva-designed email, build it directly in Canva and I can help you write the copy here." --- ## Gotcha: Generating without a budget plan **Why it matters:** Canva caps API usage at 100 requests/minute per token, and each design costs ~5 calls (autofill + export + polling). A 10-row campaign with 4 candidates per row generates 40 designs and ~200 API calls — and the math gets worse with parallelism. Without a pre-flight budget, the owner hits quota mid-campaign with no clear recovery path and four already-generated posts sitting unused. ### ✗ Bad ``` Calendar approved → immediately fire 4 candidates × 8 rows in parallel → ~160 API calls in 90 seconds → RATE_LIMIT_EXCEEDED on post 5 → loop on retry → owner blocked. ``` ### ✓ Good ``` Step 4: "8 Canva rows × 3 candidates = 24 designs, ~120 API calls. Proceed at default 3 candidates per row?" Step 6: row 1's 3 candidates fire in parallel → 30s pause → row 2 → 30s pause → row 3 → … finishes at ~12 designs/minute, well under the quota. If quota does hit anyway: stop, surface progress, ask the owner whether to drop to single candidates, pause an hour, or move to captions with what's done. ``` --- ## Gotcha: Skipping Checkpoint 1 (calendar approval) before generating assets **Why it matters:** Generating 10+ Canva designs takes API calls, time, and user attention. If the calendar has the wrong dates, wrong channels, or the owner changes their mind about a theme, all that work is discarded. The calendar checkpoint is the cheapest place to catch misalignment. ### ✗ Bad Receive the brief → immediately start calling `POST /autofills` for all 12 posts → present designs before the owner has agreed on the schedule. Owner: "Oh wait, I didn't want any posts the week of the 15th, I'm traveling." ### ✓ Good Present the calendar table first. Wait for explicit "looks good" before opening a single Canva API call. --- ## Gotcha: Template has more image slots than the brief provides photos for **Why it matters:** Multi-image social templates (Instagram carousels, product grids) can have 3+ image slots. When the brief gives you 1 photo and the template demands 3, the unfilled slots silently render Canva's stock landscape graphic — generic clouds and green hills where product photos should be. The design looks "complete" until the owner opens it. (Note: email rows skip Canva entirely in this skill — see SKILL.md Step 2. This gotcha applies only to social templates with multiple image slots.) ### ✗ Bad Build manifest with one row per design ("Carousel — needs Hero_Image"). Upload the one photo. Generate. Carousel ships with slide 1 populated and slides 2-3 both showing identical generic landscapes. ### ✓ Good Build manifest slot-by-slot. Surface the gap explicitly: ``` The "3-product carousel" template has 3 image slots. The brief gave me 1 photo. How should I fill the other 2? 1. Reuse the same photo across all 3 slots 2. I'll send you 2 more photos 3. Pick a single-image template ``` Wait for the owner's choice before generating. Don't let placeholder graphics ship. --- ## Gotcha: Trusting `status: success` without exporting and visually verifying **Why it matters:** A successful autofill job means Canva accepted the request and produced a design — not that the design contains the right images. If an `asset_id` was empty, stale, or wrong-typed, the job still returns `status: success` and the design renders with default placeholder graphics. The only way to know is to look at the rendered output. ### ✗ Bad ``` Job status: success ✓ result.design.id: present ✓ → Present to owner ``` Result: owner opens the carousel and sees stock landscape graphics in 3 of 4 designs. ### ✓ Good After the job succeeds, export each design to a permanent PNG via `POST /exports` (or `export-design` MCP). Look at each PNG and confirm it contains real assets — not Canva's default landscape, not gray rectangles, not lorem-ipsum text. Only present to the owner after visual verification passes. --- ## Gotcha: One design in a batch fails to render **Why it matters:** When 1 of 4 designs in a batch fails (job error, expired preview URL, placeholder rendered) and you present the partial carousel anyway, the owner sees three real designs and one "Show Image" gray rectangle. They lose trust in the rest of the carousel even though it's fine. ### ✗ Bad ``` Week 1 designs are ready: [Option A — real preview] [Option B — real preview] [Option C — real preview] [Option D — Show Image placeholder] Which one should I use? ``` ### ✓ Good When you detect the broken design during Step 6 verification, regenerate just that one design with the correct asset_id. Re-export, re-verify. Only present once all four designs in the batch have permanent, verified previews. If the second attempt also fails, ask the owner whether to skip, swap template, or try a different photo. --- ## Gotcha: Generating assets without confirming all autofill fields have values **Why it matters:** Canva autofill silently renders empty placeholders when a field value is missing or the referenced `asset_id` doesn't exist. The result is a professional-looking template with blank white rectangles where the product photo and headline should be. ### ✗ Bad Build calendar → immediately fire all `POST /autofills` in parallel → half the designs come back with empty image placeholders because product photos weren't uploaded first. ### ✓ Good Build calendar → inventory every autofill field slot-by-slot → upload missing product images → confirm all field values with owner → then generate designs in parallel, with every field pre-populated. --- ## Gotcha: Passing invalid values to image autofill fields **Why it matters:** When an autofill image field receives an empty string, a file path, a URL, or a stale/invalid `asset_id`, Canva does not error — it silently renders the template's default placeholder graphic (e.g., a generic landscape with clouds and hills). The design looks "finished" but the hero image is stock art, not the owner's product photo. ### ✗ Bad Upload product photo → don't wait for the upload job to complete → pass the `job_id` (not the `asset.id`) into the autofill data → design renders with a placeholder landscape instead of the product photo. ### ✓ Good Upload product photo via `POST /v1/asset-uploads` → poll `GET /v1/asset-uploads/{job_id}` until `status == "success"` → extract `asset.id` from the response → pass that exact ID into the autofill image field. Verify every image field has a confirmed `asset.id` before calling `POST /autofills`. --- ## Gotcha: Embedding Canva CDN thumbnail URLs in markdown **Why it matters:** Canva's autofill response returns short-lived, authenticated CDN URLs from `design.canva.ai`. These expire within minutes. If Claude embeds them as markdown images (`![](design.canva.ai/...)`), they render as broken "Show Image" placeholders by the time the message is shown. ### ✗ Bad Generate 8 designs → manually embed each CDN thumbnail URL in the response as `![Hero 1](https://design.canva.ai/xxx)` → all images show as broken gray placeholders because the URLs expired before render. ### ✓ Good Either let the native Cowork carousel render the tool result automatically, or export each design via `POST /exports` and embed the **permanent** export URL. As a final fallback, link to the design's permanent edit URL (`https://www.canva.com/d/{design_id}`). Never re-embed `design.canva.ai` URLs. --- ## Gotcha: Listing designs one-by-one as individual image blocks **Why it matters:** When Claude lists each design as a separate block ("Hero 1 / [image] / Hero 2 / [image]"), the images render as broken gray "Show Image" placeholders. Presenting all designs together in a single grouped batch triggers Cowork's side-by-side carousel, which renders correctly. ### ✗ Bad ``` Hero 1 — Multi-property portfolio [Show Image] View in Canva: https://canva.com/d/xxx Hero 2 — Coastal market case study [Show Image] View in Canva: https://canva.com/d/yyy ``` ### ✓ Good Present all designs in one grouped response so they render as a side-by-side carousel. Below the carousel, add a single prompt: ``` Here are 4 hero designs for Week 1. Scroll through the carousel above and let me know which one to keep. ``` --- ## Gotcha: Generating designs sequentially instead of in parallel **Why it matters:** Generating designs one at a time means the owner waits through N round trips instead of one. Fire all generation requests within a batch at once and present selection after all jobs complete. ### ✗ Bad Generate design 1 → wait → show it → generate design 2 → wait → show it → … × 8 designs. Owner watches a slow drip for 10 minutes. ### ✓ Good Fire all designs in the current batch at once → poll all jobs concurrently → once all complete, export each → verify visually → then present. --- ## Gotcha: Auto-selecting a brand template for Pro/Teams users **Why it matters:** Pro/Teams users have no brand-template API access. If Claude guesses a template by name and generates with the wrong one, the owner gets designs in the wrong colors/fonts and has to redo the work in Canva manually. ### ✗ Bad ``` Found template "Square Post - Blue". Using this for all feed posts. ``` …followed by 8 designs in blue when the brand is green. ### ✓ Good ``` I found 3 templates in your Canva library that could work for feed posts: 1. Square Post - Blue (last edited March 2026) 2. Summer Promo - Green (last edited April 2026) 3. Product Feature Card (last edited Jan 2026) Which one should I use? ``` --- ## Gotcha: Caption voice drift across a long calendar **Why it matters:** When drafting 12–20 captions in one pass, the tone tends to drift — early captions follow the brief's voice markers, later ones slip into generic marketing copy. Owners notice immediately. ### ✗ Bad Post 1: "Our handmade candles are the perfect summer gift 🌿" (matches brief: "warm, conversational") Post 10: "Elevate your ambiance with our artisanal fragrance collection." (corporate drift) ### ✓ Good Before drafting, anchor on 2–3 voice markers from the brief (e.g., "casual, friendly, uses light humor"). Re-read the first draft caption before writing each new one. If the owner flags a voice mismatch on any caption, re-read that caption and flag it as the recalibration point for the remaining drafts. --- ## Gotcha: Staging HubSpot posts without verifying `scheduledAt` is in the future **Why it matters:** HubSpot rejects posts with `scheduledAt` in the past with a validation error. If the calendar was built on an earlier date and the owner is only now staging, some dates may have passed. ### ✗ Bad Build calendar on April 1st for June posts → owner approves May 15th → try to stage without checking → post for "April 30th 10:00 AM" returns 400. ### ✓ Good Before calling `POST /social/posts`, compare each `scheduledAt` against the current UTC time. If any post date has passed, surface it: "The post scheduled for April 30th has already passed. Should I skip it, or reschedule it to next week?"