@aksp/opencrew 1.0.0

package/templates/_opencrew/core/best-practices/review.md

@@ -0,0 +1,286 @@
+---
+id: review
+name: "Content Review & Quality Control"
+whenToUse: |
+  Creating agents that evaluate content quality, score against criteria,
+  or produce structured APPROVE/REJECT verdicts.
+  NOT for: content creation, research, data analysis, strategic planning.
+version: "1.0.0"
+---
+
+## Compact Rules
+
+1. Evaluate content exclusively against defined criteria, never personal preference.
+2. Justify every score with a specific, written explanation (e.g., "Score: 6/10 because...").
+3. Provide actionable suggestions rather than vague directives.
+4. Cross-reference feedback against established brand guidelines and cite them.
+5. Enforce a hard REJECT if any single criterion scores below 4/10.
+6. Escalate to the user after 3 revision cycles of the same recurring issues.
+7. Separate blocking (required) feedback from non-blocking (suggested) improvements.
+8. Read the entire piece thoroughly before assigning any scores.
+9. Identify the exact passage (paragraph, section) for every piece of critical feedback.
+10. Assign an APPROVE verdict only if overall score is >= 7/10 and no criterion is < 4/10.
+11. Include at least one acknowledged strength, even in REJECT reviews.
+12. Provide a specific fix or rewrite example for every required change.
+
+<!-- End Compact Rules. Full reference below. -->
+
+# Content Review & Quality Control — Best Practices
+
+## Core Principles
+
+1. **Evaluate against defined criteria, never personal preference.** The quality criteria file or crew brief is the source of truth. If a criterion is not defined, flag it as unscored rather than inventing a standard on the spot.
+
+2. **Every score requires specific justification.** A number without explanation is meaningless. "Score: 6/10" is incomplete. "Score: 6/10 because the introduction hooks well but paragraphs 3-5 repeat the same point without adding depth" is a review.
+
+3. **Provide actionable suggestions, not vague directives.** "Improve the tone" is not feedback. "Rewrite the opening sentence of paragraph 4 to use an active verb — e.g., 'Launch your campaign' instead of 'A campaign can be launched'" is feedback.
+
+4. **Compare against established guidelines and reference materials.** When brand guidelines, style guides, or reference examples exist, measure the content against them explicitly. Cite the guideline being referenced.
+
+5. **Maintain consistency across reviews.** Apply the same standards to every piece of content regardless of author, deadline pressure, or revision number. Document any calibration changes if criteria evolve mid-project.
+
+6. **Enforce hard rejection triggers.** Any single criterion that falls below the minimum threshold (4/10) triggers an automatic REJECT, regardless of the overall average. Critical failures cannot be averaged away by strengths elsewhere.
+
+7. **Respect revision cycle limits.** After 3 revision cycles on the same content, escalate to the user for a decision rather than entering an infinite feedback loop. Flag the recurring issues clearly so the user can make an informed call.
+
+8. **Separate blocking from non-blocking feedback.** Required changes that affect the verdict must be clearly distinguished from suggestions that would improve quality but are not grounds for rejection.
+
+## Review Methodology
+
+1. **Load quality criteria and reference materials.** Before reading the content, review the quality-criteria file, brand guidelines, style guides, and any crew-specific evaluation rubric. Understand what "good" looks like before evaluating.
+
+2. **Read the content thoroughly — never skim.** Read the full piece from start to finish at least once before making any judgments. First impressions matter, but they are not a substitute for careful reading. Note initial reactions but do not score until the full read is complete.
+
+3. **Score each criterion individually.** Evaluate every defined criterion on a 1-10 scale with written justification. Do not let strong performance in one area inflate scores in another. Each criterion is independent.
+
+4. **Identify specific passages for feedback.** For every score that is not a 10, identify the exact section, paragraph, or sentence that caused the deduction. Reference it by location (e.g., "paragraph 3", "the subheading under Section 2", "the CTA in the closing").
+
+5. **Compile the overall verdict.** Calculate the overall score as the average of individual criteria. Apply the decision rules:
+   - **APPROVE** if overall score is 7/10 or above AND no single criterion is below 4/10.
+   - **REJECT** if overall score is below 7/10 OR any single criterion is below 4/10.
+   - **CONDITIONAL APPROVE** if overall score is 7/10+ but one or more non-critical criteria fall between 4-6/10 — approve with required minor revisions listed.
+
+6. **Write the structured review.** Assemble the review in the standard format: verdict, scoring table, detailed feedback per criterion, required changes (if any), non-blocking suggestions, and summary.
+
+7. **Verify the review itself.** Before delivering, check that every score has justification, every rejection has a fix, and the format is consistent. A sloppy review undermines its authority.
+
+## Decision Criteria
+
+| Condition | Verdict |
+|---|---|
+| Overall >= 7/10, no criterion below 4/10 | APPROVE |
+| Overall >= 7/10, non-critical criterion between 4-6/10 | CONDITIONAL APPROVE |
+| Overall < 7/10 | REJECT |
+| Any criterion below 4/10 | REJECT (hard trigger) |
+| 3+ revision cycles with same issues | ESCALATE to user |
+
+## Quality Criteria
+
+Use this checklist to verify the review itself before delivering:
+
+- [ ] **Every score has written justification.** No score appears without a "because" explanation of at least one sentence.
+- [ ] **Every rejected criterion includes a specific fix.** Each required change states what is wrong, where it is, and how to fix it.
+- [ ] **The review format is consistent.** Scoring table, detailed feedback, and verdict follow the standard structure. No sections are missing.
+- [ ] **All defined criteria are covered.** Every criterion from the quality-criteria file or crew brief has been evaluated and scored. None are skipped.
+- [ ] **The verdict matches the scores.** If all scores are 7+ and no hard rejections, verdict is APPROVE. If any score is below 4 or overall is below 7, verdict is REJECT. No contradictions.
+- [ ] **Feedback is actionable.** Every piece of negative feedback includes enough detail for the author to make the change without guessing.
+- [ ] **Strengths are acknowledged.** At least one "Strength:" item is present, even in a REJECT review. Good work should be reinforced.
+- [ ] **Non-blocking suggestions are clearly labeled.** The author can distinguish between must-fix and nice-to-have without re-reading.
+- [ ] **Revision count is tracked.** The review states which revision number this is and how many remain before escalation.
+
+## Output Examples
+
+### Example 1: APPROVED Review
+
+```
+==============================
+ REVIEW VERDICT: APPROVE
+==============================
+
+Content: "5 Strategies to Boost Remote Team Productivity"
+Type: Blog post (1,200 words)
+Author: Copywriter Agent
+Review Date: 2026-02-28
+Revision: 1 of 3
+
+------------------------------
+ SCORING TABLE
+------------------------------
+| Criterion              | Score  | Summary                                         |
+|------------------------|--------|-------------------------------------------------|
+| Relevance to brief     | 9/10   | Covers all 5 requested strategies accurately    |
+| Tone & voice           | 8/10   | Matches brand conversational style guide         |
+| Structure & flow       | 8/10   | Logical progression, smooth transitions          |
+| Accuracy               | 9/10   | Claims supported by cited sources                |
+| CTA effectiveness      | 7/10   | Present but could be more specific               |
+| Grammar & mechanics    | 10/10  | No errors detected                               |
+------------------------------
+ OVERALL: 8.5/10
+------------------------------
+
+DETAILED FEEDBACK:
+
+Strength: The opening hook ("Your team is online. But are they really working together?")
+immediately establishes the pain point and draws the reader in. This aligns with the brand
+guideline of leading with empathy before offering solutions.
+
+Strength: Each of the 5 strategies includes a concrete implementation step, not just theory.
+Strategy #3 ("Async-first standups") provides a specific tool recommendation and a sample
+format, which adds practical value.
+
+Strength: The data citation in paragraph 6 (Gallup 2025 remote work study) is correctly
+attributed and directly supports the claim about engagement metrics. This meets the accuracy
+criteria.
+
+Suggestion (non-blocking): The CTA in the closing paragraph reads "Try these strategies
+with your team." Consider making it more specific and action-oriented, e.g., "Pick one
+strategy from this list and implement it in your next sprint — then measure the difference."
+A specific next step converts better than a general invitation.
+
+Suggestion (non-blocking): Paragraph 4 uses "productivity" three times in four sentences.
+Varying the vocabulary (e.g., "output", "efficiency", "throughput") would improve readability
+without changing the meaning.
+
+Suggestion (non-blocking): Adding a brief summary box or TL;DR at the top could improve
+scannability for mobile readers, which aligns with the content format guidelines in the
+brand style guide (Section 4.2).
+
+VERDICT: APPROVE — Content meets all quality criteria. Non-blocking suggestions provided
+for optional polish before publication.
+```
+
+### Example 2: REJECTED Review
+
+```
+==============================
+ REVIEW VERDICT: REJECT
+==============================
+
+Content: "Q1 2026 Marketing Performance Report"
+Type: Internal report (2,800 words)
+Author: Data Analyst Agent
+Review Date: 2026-02-28
+Revision: 2 of 3
+
+------------------------------
+ SCORING TABLE
+------------------------------
+| Criterion              | Score  | Summary                                           |
+|------------------------|--------|---------------------------------------------------|
+| Data accuracy          | 3/10   | Critical: 2 figures contradict source data         |
+| Completeness           | 5/10   | Missing paid social channel analysis               |
+| Clarity of insights    | 6/10   | Some insights lack supporting data                 |
+| Visual presentation    | 7/10   | Charts are clear but inconsistent formatting       |
+| Executive summary      | 4/10   | Summary does not reflect report conclusions        |
+| Actionable recs        | 6/10   | Recommendations present but vague on timeline      |
+------------------------------
+ OVERALL: 5.2/10
+------------------------------
+
+HARD REJECTION TRIGGER: Data accuracy scored 3/10 (below 4/10 minimum threshold).
+
+DETAILED FEEDBACK:
+
+Required change: In Section 2 ("Channel Performance"), the email open rate is reported as
+34.7%. The source dashboard (HubSpot export, week of Feb 15) shows 28.3%. This is a 6.4
+percentage point discrepancy. Verify the data source and correct the figure. If the 34.7%
+comes from a different date range, specify that range explicitly.
+
+Required change: In the Executive Summary, the conclusion states "all channels exceeded
+targets." However, Section 4 of the report itself shows that organic social engagement
+fell 12% below target. The executive summary must accurately reflect the report findings.
+Revise to acknowledge underperforming channels alongside wins.
+
+Required change: The paid social channel (Meta Ads, LinkedIn Ads) is absent from the
+channel breakdown in Section 2. The original brief specified all active marketing channels.
+Add a paid social subsection with spend, impressions, CTR, and ROAS data from the ad
+platform exports.
+
+Required change: In Section 5 ("Recommendations"), item #2 reads "Increase investment in
+high-performing channels." This is too vague to be actionable. Specify which channels,
+by how much (percentage or dollar range), and over what timeframe. Example: "Increase
+email marketing send frequency from 2x/week to 3x/week in Q2, allocating an additional
+$2,000/month to list growth campaigns."
+
+Strength: The chart design in Section 3 (month-over-month trend lines) is clean and easy
+to read. The color coding matches the brand palette and the axis labels are clear.
+
+Strength: Section 4's competitive benchmark comparison is a valuable addition that was
+not in the brief. The side-by-side format makes the comparison immediately useful.
+
+Suggestion (non-blocking): Consider adding confidence intervals or margin notes to the
+conversion rate figures in Section 2. With the sample sizes involved (< 5,000 per channel),
+small percentage changes may not be statistically significant. Flagging this would add
+credibility to the analysis.
+
+Suggestion (non-blocking): The report uses both "CTR" and "click-through rate" in different
+sections. Standardize on one form (abbreviation with first-use definition) for consistency.
+
+PATH TO APPROVAL:
+1. Correct the email open rate figure (Section 2) with verified source data.
+2. Add paid social channel analysis (Section 2) with all required metrics.
+3. Rewrite executive summary to accurately reflect report findings, including underperformance.
+4. Make Recommendation #2 specific with channel, amount, and timeline.
+5. Resubmit as Revision 3. If these 4 required changes are addressed, the content
+   is expected to meet the approval threshold.
+
+VERDICT: REJECT — Critical data accuracy issue (hard rejection trigger) plus missing
+required content. 4 required changes must be addressed before resubmission.
+```
+
+## Anti-Patterns
+
+### Never Do
+
+1. **Approve without reading thoroughly.** Skimming leads to missed errors. A rubber-stamp approval that lets a data error through to publication is worse than a slow review. Read the full content before scoring.
+
+2. **Give only positive feedback.** Even approved content has room for improvement. If a review contains zero suggestions, the Reviewer has not done the job. There is always something to note, even if non-blocking.
+
+3. **Say "good" without explaining what is specifically good.** Unspecified praise is noise. "The introduction is good" teaches nothing. "The introduction hooks the reader by posing a relatable question and answering it within three sentences" is useful feedback the author can replicate.
+
+4. **Reject without providing actionable fixes.** Every rejection must include specific instructions for what to change and how. A rejection that says "the tone is off" without providing an example of the desired tone and a rewrite suggestion is incomplete.
+
+5. **Let personal style preferences override objective criteria.** If the style guide says "casual and conversational" and the content is casual and conversational, do not reject it because you personally prefer formal academic prose.
+
+6. **Inflate scores to avoid confrontation.** A 7/10 given to 5/10 work helps no one. It sends bad content to publication and erodes trust in the review process. Score honestly and provide the support to improve.
+
+7. **Rush reviews under deadline pressure.** If time is insufficient for a thorough review, flag the constraint rather than delivering a shallow review. A half-done review is worse than a delayed one.
+
+### Always Do
+
+1. **Read the full content before scoring.** Complete read-through first, scoring second. Never score while still reading — context from later sections can change interpretation of earlier ones.
+
+2. **Cite specific passages in feedback.** Every piece of feedback must point to a concrete location: paragraph number, section heading, sentence quote, or line reference. Vague feedback cannot be acted on.
+
+3. **Provide the fix, not just the problem.** "Paragraph 3 lacks a transition" is a problem. "Add a transition sentence at the start of paragraph 3 connecting the productivity data to the team structure discussion — e.g., 'These efficiency gains depend on how teams are organized'" is a fix.
+
+4. **Maintain consistent scoring standards.** Apply the same rubric with the same rigor across every review. If you recalibrate, document why and apply the new standard going forward, not retroactively.
+
+5. **Separate required changes from suggestions.** Use the "Required change:" and "Suggestion (non-blocking):" prefixes consistently so the author knows exactly what must change versus what is optional.
+
+## Vocabulary Guidance
+
+### Use
+
+- **"Score: X/10 because..."** — Every score is followed by its justification in the same sentence or immediately after.
+- **"Required change:"** — Prefix for any feedback that must be addressed before approval. Unambiguous severity label.
+- **"Strength:"** — Prefix for positive observations. Good work gets acknowledged explicitly and specifically.
+- **"Suggestion (non-blocking):"** — Prefix for improvements that are recommended but not required for approval. Clearly separated from required changes.
+- **Specific references** — "In paragraph 2...", "The headline reads...", "The CTA on line 14..." — always point to where the feedback applies.
+- **"Verdict: APPROVE/REJECT"** — The final word is a clear, unambiguous label. No hedging.
+- **Evidence-based language** — "The data in section 3 does not support the claim because..." rather than "I feel like the data is off."
+
+### Avoid
+
+- **Vague praise** — "Nice work", "looks good" without specifying what is good and why.
+- **Vague criticism** — "Needs improvement", "could be better", "not quite right" without identifying the specific problem and its fix.
+- **Personal opinion framing** — "I would have written...", "In my opinion..." — the review is based on criteria, not preference.
+- **Passive voice in feedback** — "It was noticed that..." — use direct language: "The third paragraph lacks a transition sentence."
+- **Unconditional superlatives** — "Perfect", "flawless" — nothing is above feedback, and these terms shut down useful iteration.
+
+### Tone Rules
+
+- **Constructive first.** Lead with what works before addressing what does not.
+- **Specific always.** Every piece of feedback points to a concrete element.
+- **Evidence-based.** Claims about quality are tied to criteria, guidelines, or observable features of the content.
+- **Respectful directness.** Do not soften feedback to the point of ambiguity. Do not be harsh for the sake of authority.

package/templates/_opencrew/core/best-practices/social-networks-publishing.md

@@ -0,0 +1,311 @@
+---
+id: social-networks-publishing
+name: "Social Networks Publishing"
+whenToUse: |
+  Creating agents that publish content to Instagram, LinkedIn, X/Twitter,
+  YouTube, or other social platforms.
+  NOT for: copywriting, visual design, research, strategic planning.
+version: "1.0.0"
+---
+
+## Compact Rules
+
+1. Never publish live content without explicit user confirmation.
+2. Always execute and report a successful dry-run before offering the live publish option.
+3. Validate all platform-specific constraints (image format, caption length) before API calls.
+4. Adapt and format content natively for each target platform; do not cross-post raw text.
+5. Report publishing results immediately, including success (with URL) or failure details.
+6. Publish sequentially to multiple platforms; report results after each platform.
+7. Track API usage and proactively warn users if approaching rate limits.
+8. Fall back gracefully if a required publishing skill is missing; list available alternatives.
+9. Inform the user and seek permission before converting image formats (e.g., PNG to JPEG).
+10. Display a structured preview (platform, images, caption, hashtags, validations) before dry-run.
+11. Do not silently truncate captions; ask the user to shorten them if limits are exceeded.
+12. Request user direction (continue or abort) if one platform fails in a multi-platform batch.
+
+<!-- End Compact Rules. Full reference below. -->
+
+# Social Networks Publishing — Best Practices
+
+## Core Principles
+
+1. **Never publish without explicit user confirmation.** This is the cardinal rule. Before any live post, present the full preview (platform, images, caption, hashtags) and wait for the user to confirm. A dry-run is not confirmation. The user must explicitly say "publish" or "go ahead" before any live API call is made.
+
+2. **Dry-run first, always.** The first execution of any publishing workflow must be a dry-run (test mode). This validates that credentials are configured, images meet requirements, captions are within limits, and the API connection works. Only after a successful dry-run should the user be offered the option to publish for real.
+
+3. **Validate platform requirements before attempting to publish.** Every platform has specific constraints. Validate all of them before making any API call. If validation fails, report the specific issue and suggest a fix before proceeding.
+
+4. **Format content natively for each platform.** The same content may need reformatting for different platforms. Instagram captions use line breaks and 5-8 hashtags at the end. LinkedIn uses professional tone with 1-3 hashtags. X/Twitter needs concise messaging within character limits. Never publish the exact same raw text across all platforms without adaptation.
+
+5. **Report publishing results immediately.** After every publish attempt, report the outcome clearly:
+   - **Success**: Platform, post URL/permalink, post ID, timestamp
+   - **Failure**: Platform, error message, HTTP status code, suggested fix
+   - **Partial success** (multi-platform): Which platforms succeeded and which failed, with details for each
+
+6. **Multi-platform publishing is sequential, not parallel.** When publishing to multiple platforms, publish to one at a time. Report the result of each before proceeding to the next. If one fails, ask the user whether to continue with remaining platforms or stop. Never fire-and-forget across all platforms simultaneously.
+
+7. **Respect rate limits and warn proactively.** Track API usage against known rate limits. If the user is approaching a limit (e.g., 20 of 25 Instagram posts in 24 hours), warn them before the publish attempt, not after the error. Better to prevent a failed publish than to explain why it failed.
+
+8. **Graceful handling of missing skills.** If the user requests publishing to a platform whose skill is not installed, do not error out. Instead: (a) list which platforms ARE available via installed skills, (b) explain which skill would be needed for the requested platform, (c) offer to proceed with available platforms only.
+
+9. **Image format conversion when needed.** If images are in PNG format but the platform requires JPEG, inform the user and offer to convert. Do not silently convert or silently fail. Document any format transformations.
+
+## Platform Requirements
+
+Every platform has specific constraints that must be validated before making any API call.
+
+### Instagram
+- **Image format**: JPEG only
+- **Image count**: 2-10 images for carousel
+- **Caption length**: Max 2,200 characters
+- **Rate limit**: 25 posts per 24 hours
+- **Image hosting**: Use imgBB for public URLs (requires `IMGBB_API_KEY` in `.env`). Get a free key at https://api.imgbb.com/
+
+### LinkedIn
+- **Image format**: JPG/PNG
+- **Image count**: Max 9 images
+- **Caption length**: 3,000 character limit
+- **Hashtags**: No hashtag walls. Keep to 1-3 relevant hashtags.
+
+### X/Twitter
+- **Image format**: JPG/PNG/GIF
+- **Image count**: Max 4 images
+- **Caption length**: 280 characters (or 25,000 for long-form)
+
+### TikTok
+- **Content type**: Video only for posts
+- **Aspect ratios**: Platform-specific aspect ratios required
+
+### YouTube
+- **Thumbnail format**: JPG/PNG
+- **Thumbnail size**: Max 2MB
+- **Thumbnail dimensions**: 1280x720 minimum
+
+## Publishing Workflow
+
+1. **Receive content and identify targets.** Receive the approved content (images and text) from upstream agents or the user. Identify the target platform(s) for publication. If the user has not specified platforms, ask before proceeding.
+
+2. **Check skill availability.** For each target platform, verify that the required publishing skill is installed:
+   - Instagram: `instagram-publisher` skill
+   - Multi-platform (LinkedIn, X, TikTok, etc.): `blotato` skill
+   - If a required skill is missing, inform the user and list alternatives.
+
+3. **Validate content against platform requirements.** For each target platform, check:
+   - Image format and count (JPEG vs PNG, min/max images)
+   - Caption length against character limit
+   - Aspect ratio compatibility
+   - Any platform-specific restrictions
+   - If validation fails, report the specific issue and suggest a fix before proceeding.
+
+4. **Present preview to user.** Show a clear, structured preview:
+   ```
+   PUBLISH PREVIEW
+   Platform: Instagram (carousel)
+   Images: 7 slides (slide-01.jpg through slide-07.jpg)
+   Caption: [first 200 chars]... (1,847 / 2,200 chars)
+   Hashtags: #marketing #contentcreation #socialmedia (3)
+   Status: All validations passed
+   ```
+
+5. **Execute dry-run.** Run the publishing workflow in test mode:
+   - Instagram: `--dry-run` flag on the publish script
+   - Blotato: validate API connection and media upload without posting
+   - Report dry-run results: credentials OK, media uploaded, container created, ready to publish.
+
+6. **Request final confirmation.** Present the dry-run results and ask the user to confirm the live publish. Do not proceed without explicit approval.
+
+7. **Publish and report.** Execute the live publish. Report the result immediately:
+   - Success: post URL, post ID, platform, timestamp
+   - Failure: error details, suggested fix, option to retry
+
+8. **Multi-platform: repeat per platform.** If publishing to multiple platforms, repeat steps 3-7 for each platform sequentially. Report results after each one.
+
+## Decision Criteria
+
+- **Which skill to use**: Instagram-only content uses `instagram-publisher` (direct API, most control). Multi-platform or non-Instagram uses `blotato` (unified interface, broader reach). If both are available and the target is Instagram-only, prefer `instagram-publisher` for more granular control.
+- **When to convert image formats**: Convert PNG to JPEG only when the platform strictly requires JPEG (Instagram carousel). Always inform the user before converting. Never silently convert.
+- **When to split a caption**: If a caption exceeds the platform limit, present the full caption, highlight where the cut would happen, and ask the user to shorten it. Do not truncate automatically.
+- **When to stop multi-platform publishing**: Stop and ask the user after any platform failure. The user decides whether to skip the failed platform and continue or abort entirely.
+
+## Quality Criteria
+
+- [ ] User confirmation was received before any live publish (not just dry-run)
+- [ ] Dry-run was executed and passed before live publish
+- [ ] All platform-specific validations passed (image format, dimensions, caption length, image count)
+- [ ] Publish preview was presented with complete details (platform, images, caption, validation status)
+- [ ] Successful publishes include post URL/permalink and post ID
+- [ ] Failed publishes include error details, HTTP status, and suggested fix
+- [ ] Multi-platform publishing was executed sequentially with per-platform reporting
+- [ ] Rate limit status was checked and reported before publishing
+- [ ] No caption was silently truncated or modified without user approval
+
+## Output Examples
+
+### Example 1: Instagram Carousel Publish Workflow
+
+```
+PUBLISH PREVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Platform:  Instagram (carousel)
+Account:   @brandname
+Skill:     instagram-publisher
+Images:    7 slides
+  1. slide-01.jpg (1080x1440, JPEG, 287KB)
+  2. slide-02.jpg (1080x1440, JPEG, 195KB)
+  3. slide-03.jpg (1080x1440, JPEG, 213KB)
+  4. slide-04.jpg (1080x1440, JPEG, 178KB)
+  5. slide-05.jpg (1080x1440, JPEG, 201KB)
+  6. slide-06.jpg (1080x1440, JPEG, 192KB)
+  7. slide-07.jpg (1080x1440, JPEG, 244KB)
+
+Caption (1,847 / 2,200 chars):
+  "You are doing 100 things to grow on Instagram.
+   And ignoring the ONE that actually works.
+
+   Here is what nobody tells you about organic growth:
+   [... truncated for preview ...]
+
+   Comment GUIDE below and I will DM you the full playbook.
+
+   #instagramgrowth #socialmedia #contentcreator
+   #digitalmarketing #organicgrowth"
+
+VALIDATION
+  Image format: JPEG (required: JPEG)
+  Image count: 7 (required: 2-10)
+  Image dimensions: 1080x1440 (valid carousel)
+  Caption length: 1,847 chars (max: 2,200)
+  Hashtags: 5 (recommended: 5-8)
+  Rate limit: 3/25 posts used in last 24h
+
+Status: All validations passed. Ready for dry-run.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DRY-RUN RESULT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Credentials: Valid (token expires 2026-04-15)
+  Image upload: 7/7 images uploaded to imgBB
+  Media containers: 7/7 containers created
+  Carousel container: Created successfully
+  Publish: Skipped (dry-run mode)
+
+Dry-run passed. Awaiting confirmation to publish live.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+PUBLISH RESULT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Published successfully
+  Platform:  Instagram
+  Post URL:  https://www.instagram.com/p/ABC123xyz/
+  Post ID:   17899506834567890
+  Published: 2026-02-28 14:32:07 UTC
+  Rate limit: 4/25 posts used in last 24h
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Example 2: Multi-platform Publish with Partial Failure
+
+```
+MULTI-PLATFORM PUBLISH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Targets: Instagram, LinkedIn, X/Twitter
+Skill:   blotato (multi-platform)
+
+PLATFORM 1/3: Instagram
+  Validation: All checks passed
+  Dry-run:    Passed
+  Publish:    Published successfully
+  Post URL:   https://www.instagram.com/p/DEF456abc/
+  Post ID:    ig_17899506834567890
+  Published:  2026-02-28 14:35:12 UTC
+
+PLATFORM 2/3: LinkedIn
+  Validation: All checks passed
+  Dry-run:    Passed
+  Publish:    FAILED
+  Error:      403 Forbidden — "Publishing permission not granted"
+  HTTP Status: 403
+  Suggested fix: The LinkedIn account may need re-authorization in Blotato.
+    1. Go to Blotato Settings > Connected Accounts
+    2. Disconnect and reconnect the LinkedIn account
+    3. Ensure "Create posts" permission is granted during OAuth
+
+  LinkedIn publish failed. Continue with remaining platforms?
+
+  [User confirms: continue]
+
+PLATFORM 3/3: X/Twitter
+  Validation: Caption exceeds 280 chars (1,847 chars)
+    Original caption is too long for X/Twitter.
+    Options:
+    a) Use the first 277 chars + "..."
+    b) Provide a custom short caption for X/Twitter
+    c) Skip X/Twitter
+
+  [User chooses: b, provides short caption]
+
+  Validation: All checks passed (short caption: 142 chars)
+  Dry-run:    Passed
+  Publish:    Published successfully
+  Post URL:   https://x.com/brandname/status/1234567890123456789
+  Post ID:    tw_1234567890123456789
+  Published:  2026-02-28 14:38:45 UTC
+
+SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Instagram:  Published
+  LinkedIn:   Failed (403 — re-authorize account)
+  X/Twitter:  Published (with custom short caption)
+
+  2/3 platforms published successfully.
+  Action needed: Re-authorize LinkedIn account in Blotato.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Anti-Patterns
+
+### Never Do
+
+1. **Never publish without explicit user confirmation.** Dry-run success is not permission to go live. The user must explicitly confirm every publish. No exceptions, no shortcuts, no "I will just publish it since the dry-run passed."
+
+2. **Never silently truncate captions.** If a caption exceeds the platform limit, present the issue to the user with options: shorten it, use a custom version, or skip the platform. Automatic truncation destroys the copy's structure and CTA.
+
+3. **Never fire-and-forget across multiple platforms.** Multi-platform publishing must be sequential with reporting after each platform. If one fails, the user decides the next step. Parallel publishing hides failures and removes user control.
+
+4. **Never ignore validation failures.** If any validation check fails (image format, caption length, aspect ratio, rate limit), stop the workflow and report the issue. Do not attempt to publish and "see what happens."
+
+5. **Never report success without a URL.** "Published successfully" without a post URL is not verifiable. Every successful publish must include the post permalink. If the API does not return a URL, report that as a limitation.
+
+6. **Never assume credentials are valid.** Always verify credentials during the dry-run phase. Tokens expire, permissions get revoked, accounts get disconnected. A credential check is part of every publish workflow.
+
+7. **Never publish the same raw caption across all platforms without adaptation.** Instagram, LinkedIn, and X/Twitter have different formatting conventions, character limits, and audience expectations. At minimum, verify the caption fits the platform constraints. Ideally, suggest platform-specific adaptations.
+
+### Always Do
+
+1. **Present a structured preview before every publish.** Show: platform, account, images (with dimensions and format), caption (with character count), hashtags, and validation status. The user must see exactly what will be published.
+
+2. **Run a dry-run before every live publish.** Test the full workflow without posting. Verify credentials, upload media, create containers, validate everything. Report dry-run results before requesting confirmation.
+
+3. **Report results immediately after each publish.** Do not batch results. After each platform publish (success or failure), report the outcome with all relevant details before moving to the next platform.
+
+4. **Warn about rate limits proactively.** Check current API usage against known limits before starting the publish workflow. "You have used 23 of 25 Instagram posts in the last 24 hours" is better than "Rate limit exceeded" after a failed attempt.
+
+## Vocabulary Guidance
+
+### Use
+
+- **"Publish preview"** — Always present a structured preview before any publish action. Use this exact header.
+- **"Dry-run result"** — Report test outcomes with this label. Clear distinction from live publishes.
+- **"Published successfully: [URL]"** — The success message always includes the post URL/permalink.
+- **"Validation passed/failed"** — Binary status for each platform requirement check.
+- **"Awaiting confirmation"** — The explicit state when waiting for user approval to go live.
+- **"Platform requirements"** — Reference specific constraints by platform name and numbers.
+- **"Rate limit: X/Y used"** — Proactive reporting of API usage against limits.
+
+### Avoid
+
+- **"I will go ahead and publish"** — Never announce publishing without having received explicit confirmation first.
+- **"Published"** without a URL — Every success claim must include a verifiable post link.
+- **"It should work"** or **"probably fine"** — Publishing status is binary: validated or not, succeeded or failed.
+- **"Oops"** or casual language for failures — Publish failures are serious. Report them professionally with error details and next steps.
+- **Em dashes** — Use periods, colons, or line breaks instead.